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> The Widest Range of 32-bit Intel x86 Platforms 


32-bit DOS, 32-bit Windows, OS/2 2.0, AutoCAD ADS 


> The Industry’s Leading Code Optimizer — 
Advanced global optimizer with new 486 ae izations 

> The Most Comprehensive Toolset = = $#— 
Debugger, profiler, protected-mode comma and fir ne 
32-bit DOS extender with royalty-free run-time, licens 
components from Microsoft SDK, and more — —— 


> The Best Value in 32-Bit Tools: sas" — 


Unleash 32-bit Power! 
WATCOM C9.0/386 lets you exploit the two key 32-bit per- 
formance benefits. The 32-bit flat memory model simplifies 
memory management and lets applications address beyond 
the 640K limit. Powerful 32-bit instruction processing delivers 
a significant speed advantage: typically at least a 2x speedup. 
You Get: 
> 100% ANSI and SAA compatible: C9.0/386 passes all Plum Hall 

Validation Suite tests 
> Extensive Microsoft compatibility simplifies porting of 16-bit code 
> Royalty-free run-time for 32-bit DOS, Windows and OS/2 apps 
> Comprehensive toolset includes debugger, linker, profiler and more 
> DOS extender support for Rational, Phar Lap and Ergo 
> Run-time compatible with WATCOM FORTRAN 77/386 
32-bit DOS support includes the DOS/4GW 32-bit DOS extender by 
Rational Systems with royalty-free runtime license 

> Virtual Memory support up to 32Mb 
32-bit Windows support enables development and debugging of 
true 32-bit GUI applications and DLLs. 

> Includes licensed Microsoft SDK components 
32-bit OS/2 2.0 support includes development for multiple target 
environments including OS/2 2.0, 32-bit DOS and 32-bit Windows 

> Access to full OS/2 2.0 API including Presentation Manager 

> Integrated with IBM Workframe/2 Environment 
AutoCAD ADS ana ADI Development: Everything you need to 
develop and debug ADS and ADI applications for AutoCAD Release 11 


Novell’s Network C for NLM’s SDK includes C/386 





The iadestey? s Choice. 

Autodesk, Robert Wenig, Manager, AutoCAD for Windows: 
“At Autodesk, we're using WATCOM C/386 in the development 
of strategic new products since it gives us a competitive edge 
through early access to new technologies. We also highly 
recommend WATCOM C/386 to third party AutoCAD add-on 
(ADS and ADI) developers.” 


Fox Software, David Fulton, President: “FoxPro 2.0 itself is 
written in WATCOM C, and takes advantage of its many superior 
features. Optimizing for either speed or compactness is not 
uncommon, but to accomplish both was quite remarkable.” 


GO, Robert Carr, Vice President of Software: “After looking at the 
32-bit Intel 80x86 tools available in the industry, WATCOM C was 
the best choice. Key factors in our decision were performance, 
functionality, reliability and technical support.” 


IBM, Jobn Soyring, Director of OS/2 Software Developer Programs: 
“IBM and WATCOM are working together closely to integrate these 
compilers with the OS/2 2.0 Programmer’s Workbench.” 


Lotus, David Reed, Chief Scientist and Vice President, Pen-Based 
Applications: “In new product development we're working with 
WATCOM C because of superior code optimization, responsive 
support, and timely delivery of technologies important to us like 
p-code and support for GO Corp’s. PenPoint.” 

Novell, Nancy Woodward, VP and G.M,, Development Products: 
“We searched the industry for the best 386 C compiler technology 
to incorporate with our developer toolkits. Our choice was 
WATCOM.” 








WATCOM C9.0/386 


> 100% ANSI C optimizing compiler J’ Be 

> Protected-mode compiler » OS/2 > 

hosted-compiler > Royalty-free DOS > COMPUTER 

extender with VMM support » Licensed TA aif | ANGUAGE 
components of the Microsoft Windows SDK 
> Interactive source-level debugger » Linker | AWARD 

> Protected-mode linker » OS/2-hosted linker » Profiler ae | q 

> Object code librarian » Object code disassembler ® MAKE = Hh iia” | 

facility » Patch facility ® Object module convert utility eee | : mNelig 

> Windows supervisor > Bind facility for Windows applications a | | 

> 32-bit run-time library object code » Special 32-bit libraries : “s EDITORS’ 

for Windows API » Graphics library for Extended DOS : ee ie | 

applications » 32-bit Run-time libraries for Windows » 32-bit wneni0compatePobs — NaeonCvenen6s | WA 

Run-time libraries for OS/2 


Special Offer 
Buy WATCOM C9.0/386 and you'll be eligible to obtain: 


1-800-265-4555 
WATCOM C9.0 Delta Pack provides you with the tools necessary to : = 
develop and debug 16-bit applications for DOS, Windows, and OS/2. The Leader in 1 32 2-bit Development Tools 
Only $99. ($495 comparative separate cost) 
415 Phillip Street, Waterloo, Ontario Canada 
Telephone: (519) 886-3700, Fax: (519) 747-4974 


r - _f mo f° . pe ; Price does mot include freight and tawes w mere applicable. Authorized dealers may sell for less 
WATCOM FORTRAN if /386 Delta Pack provides you with WancoM C and Lightning Devic co a r Pe ATC oo stems Inc _ 
aca Bea . - “4 = DOS46 and DOS 6M trademarks af onal Syste t 
everything necessary to develop and debug 32-bit FORTRAN Other trademarks ae he proper s of thei respective owners 
: ay a : iy “ig - Copyright 1992 WATCOM Products Inc 
applications for extended DOS, 32-bit Windows and OS/2 2.0. ee 


Only $399. ($895 comparative separate cost) 











Keeping your User Interiace 
Options Open with 
Dialog System trom Micro Focus. 


Developing the right user interlace for your business application is 
crucial, but how do you know which ‘industry-standard’ will offer you the 
most flexibility? Is it Microsoft® Windows™? OS/2® Presentation Manager”? 
Or perhaps just Character Mode interfaces for DOS and UNIX? 

It doesn’t matter...because with Dialog System” from Micro Focus, 
you can develop GUIs that will run unchanged in all of those 


environments, adapting to the look and feel of your target. 





Dialog System supports high-level development of graphical and 
character-based user interfaces. It isolates screen and keyboard 


logic from the COBOL application’s code, replacing 


hundreds of lines of screen definition with a simple FRE 7% apicyete 
ah | 2B Fi = 

CALL statement. Which, in turn, means smaller, and %, ss 

— ; f “a 

faster GUI applications that can be easily maintained. 7ty % 


Z 





Dialog System also keeps your options open. Graphical user 
interfaces can be prototyped, developed, even customized without impacting 
the program code...and those same interfaces will run unchanged even in 
emulation mode in character-based environments. 

Combine flexibility and performance and the solution to the 
graphical user interface development puzzle is simple: Dialog System. 

Keep your user interface options open with Dialog System. 
Call 800-872-6265 and discover “A Better Way of Programming ” 


with Micro Focus. 


| | 
| 


: r : 4 7 : | ql il 3 =) % - | = ¥ 
Micro Focus Inc., 2465 East Bayshore Road, Palo Alto, CA 94303. Tel: (415) 856 4161. 


Micro Focus is a registered trademark and Dialog System and “A Better Way of Programming” are trademarks of Micro Focus Inc. All other products are trademarks of their respective companies. 
GSA Contract Number GSOOK90AGS5251-PS02. 
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Editor’s Comments 


As promised, we started an OS/2 Developer topic 
on CompuServe™ (look for us in the OS2DF2 
forum, section 13). Thanks to everyone for your 
praise, encouragement, and ideas. A common 
thread in many notes was your desire for more 
“beef” in the articles. We don’t have space to print 
all of our mail, but here are some excerpts: 


[vous hope that future issues would have 
more articles on the “picky details” of 
programming for OS/2™ along with code. 
There are a great number of developers out 
here who are totally new to OS/2, as well as a 
number of semi-experienced developers. Space 
has to be devoted to both groups. You should 
also cover CSet/2. Further, OS/2 Developer 
should deal with real-world problems. 
Developers are hungry for useful information, 
and you have to fill that need. By the way, 
quarterly is far too long between issues. At the 
very least, they should be bimonthly. 
Programmers need information now— 
tomorrow may be too late! —Tony Costanza 


ore “beef”... yes yes yes!... 
—Shetla S. Ruth 


[vce like to see OS/2 Developer have more 
technical articles of some depth, 
accompanied by a lot of source code (with 
code available in electronic form as well). 


The market for in-depth technical information 
about OS/2 programming is scarcely 
saturated. Containers. Notebooks. 
Programming the COM port. Printing to the 
spooler. Managing fonts. Multi-threading 
techniques and semaphores to manage 
threads. Intro to WPS programming. Fast 
screen redraw with GpiBitBlt. Converting from 
16-bit to 32-bit OS/2. Converting from DOS to 
OS/2. Converting from Windows™ to OS/2 


PM. Converting from C to C++. Using pipes 
and queues. Using DDE. Using various data 
formats for the clipboard. Mixing text colors 
and fonts in a single document. Design issues and 
CUA 91. Optimizing PM programs. Window 
management (sizing, placement, Z-ordering, 
owner and parent relationships, HWND_OBJECT use, 
and so on). Using the new font and file dialogues. 
Sliders. Value sets. Device drivers. Debugging 
multi-threaded programs. Debugging PM 
programs. Creating and using DLLs. 


All of these are how-to articles. I would also 
like survey articles of available programming 
tools, including GUI builders, C++ class 
libraries, CASE tools, editors, and so on. These 
should be hands on pieces, not just a 
regurgitation of features—how are the tools to 
use? —Wayne Kovsky 


[li the magazine quite well; I just wish 
there was more of it. | don’t know if 
monthly is the answer, but six issues a year 
would be an improvement. I like the articles 
by ISVs; I don’t mind the hype too much, since 
most of them have been revealing as to what 
the development staff went through. Others 
provide insight into ways OS/2 is being used 
in the real world. Keep up the good work. 
—Dave Bennett 


[e like to see more PM, WPS, and SOM 
source code. You’ve started off pretty well 
with the SOM stuff. It would be great to have 
something like a Orfali and Harkey-type 
column that progresses from a simple 
ClubMed type of system and eventually gets 
more complex from issue to issue. 


I keep my source code magazines forever. 
Applicable source code from cover to cover 
would make a large stack of OS/2 Developers 





Dick Conklin 


You asked for 
more “beef,” 
and we're going 
to deliver it. 
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part of the Fishman clutter. And my 
subscription never lapses on that type of 
magazine! —Rick Fishman 


i= let me compliment you on the 
excellent job you have done on OS/2 
Developer. It has always been most impressive 
and helpful in providing high-level articles. 


However, the past focus has been on high- and 
medium-level discussions of features as well 
as ISV articles. I don’t think either of these 
quite constitute the “beef” that has been asked 
for. What developers want to see is, I believe, 
working code and a detailed discussion of how 
to write programs. | would like to see complete 
code for all articles uploaded to CompuServe 
as complete, working, sample programs. 
Printing only key abstracts in the magazine is 
fine, but a more complete example would be 
most helpful. —Guy Scharf 


ood to have you up here. I strongly 
agree with all the “beef” requests. 
How about a second edition of 
OS/2 Notebook? —Jon Wright 








Thanks, everyone! You asked for more beef, and 
we're going to deliver it. We're also asking our 
writers to upload the source code of their sample 
programs on CompuServe. We're almost finished 
with the second edition of the OS/2 Notebook, a 
compilation of articles from this magazine, due in 
early 1993. We are also planning further changes to 
the magazine, including a new format designed to 
deliver more articles in each issue and a possible 
increase in publication frequency. 


If you haven't joined us on CompuServe, please 
drop by and say hello. We'd like to hear from you. 


Dik Gbhl 


No Matter What Your GUI Destination 





CASEWORKS 


Can Take You There 








Now You Don’t Have to Worry About Choosing the 


Wrong GUI Development 


Path...CASEWORKS Lets You Easily Change Direction — by Switching 
Languages or Platforms — Without Wasting Any Time! 


All of the choices surrounding Graphical User Interfaces 
(GUIs) can make picking a GUI development path seem 
impossible. Deciding between Windows™ or Presenta- 
tion Manager™ (PM)is only the first step toward building 
client/server applications. You need a tool that lets you 
generate code to Windows or PM for a variety of languages 
and APIs, and that lets you migrate interfaces among 
languages and platforms if you change your mind. 
CASE:-W™ and CASE:PM™ are the only tools that give you 
that flexibility. 


CASE:W for Windows Development 


Windows developers face the challenge of migrating 
from C to C++ and class library programming. CASE:W 
makes it easy by generating source code for the three 
“standards” of Windows programming: the Windows C 
API, Microsoft Foundation Classes™ and Borland’s 
ObjectWindows™., 

Simply buy CASE:W along with a “Knowledgebase” 
for C, or C++ and a class library. Use the visual designer 
to create and test your interface. Then generate expert- 
level, tightly-written, thoroughly-documented code from 
your knowledgebase. To use the interface in a different 
environment, simply buy that knowledgebase and generate 
again. You can even migrate the interface to PM. 


CASE:PM for Presentation Manager Development 
When you're developing “mission-critical” applications 
for OS/2™2.0, you need astrategic tool that can build PM 
applications for both 16- and 32-bit PM environments. 
Our new CASE:PM VIP tool gives you a head start on 
building client/server applications, and lets you easily 
migrate legacy applications to OS/2 2.0. Plus, you can 
leverage all the advanced capabilities of CUA ‘91. 


The Safest Development Route 

With CASEWORKS, you get the security of using the 
leading GUI development tools. Microsoft” includes a 
version of CASE:W with its QuickC™ for Windows, and 
more corporations use CASE:PM for developing strategic 
PMand client/server applications than any other standard 
language tool. Both tools generate code without 
restrictions, letting you add any code, anywhere. Plus, a 
regeneration facility preserves your changes. And you 
control the generated code, with no proprietary 
languages, runtimes or licensing fees. 

Don't avoid making a decision because you're un- 
certain which way to go. Choose the only company that 
can take you to Windows or PM, through any develop- 
ment route: CASEWORKS. 


CASEVWORKS' 
1 Dunwoody Park, Suite 130, Atlanta, GA 30338 
1-800-635-1577 © (404) 399-6236 © Fax (404) 399-9516 
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Spotlight on Computer Associates 


CA’s Success: 


Platform-Adaptive 


Applications 


by Eric Nelson 


( omputer Associates International Inc. 

(CA) is a leading provider of integrated 
systems management, database management, 
application development, and business 
applications software. CA, which creates 
programs that operate on mainframe, 
midrange, and desktop computers, is one of 
the few companies in the world to have sucha 
broad coverage of applications for every major 
computing platform. 


In 1976, Charles B. Wang, Russ Artzt, and 
Judith Cedeno founded Computer Associates 
in New York City. Wang is currently CA’s 
chair, Artzt is executive vice president for 
research and development, and Cedeno is the 
company’s corporate services director. CA 
moved its headquarters to Islandia, New York, 
in early 1992. 


CA’s first product was CA-SORT™, a sort 
utility for IBM’s Virtual Machine™ (VM) 
mainframes. By the end of its first year, the 


company had over 200 clients and was 
marketing an assortment of VM utilities, such 
as IDOS/VS™, EXECMOD™, and 
SYMBUG"™. Over the next few years, CA 
created or acquired more products and 
migrated them to other mainframe 
environments and midrange computers. The 
company then entered the desktop market, 
creating applications for UNIX™ workstations, 
DOS- and Windows'-based personal 
computers, and the Macintosh™. Currently, 
Computer Associates offers well over 300 
products covering 
every major 
computing 
platform. Platforms 
supported are listed 
in Figure 1. Most of 
its products are 
compliant with the 
1991 Systems 
Application 
Architecture™ 
(SAA) Common 
User Access™ 
(CUA) guidelines, 





CA founder Charles Wang 


Today, with over 90% of Fortune 500 
companies using CA software, CA’s revenues 
for 1992 exceeded $1.5 billion. The company 
has 7,400 employees and operates in 27 
countries, with over 40% of its sales coming 
from overseas. Distribution channels include 
retail stores, mail order, value-added resellers, 
and a corporate sales force. 


OS/2 PRODUCTS 


Computer Associates is porting seven 
products to OS/2 2.0, six from Windows, and 
one from UNIX: 


feel ina lias 





* ACCPAC Simply Accounting™, an 
accounting package for small businesses 


¢ CA-Textor™, the company’s word processor 


* CA-Compete!™, a data modeling and 
decision support tool that combines a 
database and a multidimensional 
spreadsheet 


* CA-dBFast™, a graphical Xbase language 
and development tool 


¢ CA-SuperProject™, CA’s project 
management tool 


* CA-REALIZER™, a graphical BASIC 


development tool 


¢ CA-UNICENTER™, a comprehensive system 
management tool that includes security, 
storage management, production control, 
scheduling, report distribution, resource 
accounting, performance monitoring, data 
center automation, and LAN management for 
NetWare and LAN Services. CA- 
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CA's central 
design 
philosophy: 
a “computer 
architecture 


for the 90s.” 


UNICENTER, the company’s most popular 
product, has until now been available only on 
mainframe and midrange computers. A 
screen from CA-UNICENTER for OS/2 is 
shown in Figure 2; user interfaces such as this 
are similar across platforms. 


COMPUTER ARCHITECTURE 
FOR THE 90S 


Computer Associates’ programming 
philosophy is “to provide consistent, 
integrated functionality across products and 
across platforms with a platform-adaptive user 
interface.” One of the keys to its cross-product 
and cross-platform consistency, and to CA’s 
ability to port rapidly, is the company’s central 
design philosophy: “Computer Architecture 
for the 90s,” or CA90s. 


CA90s is a software architecture designed to: 


* Keep as much code as possible platform- 
independent. 


IBM OS/2 Developer 











User Interface 
and Visualization Services Layer 


10 


CA90s 
encourages 
developers to 
reuse code by 
insulating the 
parts of the 
application that 
change from 
platform to 
platform. 


¢ Put as much code as possible in common 
service layers available to all applications. 


* Provide for communications between, and 
integration of, applications running on the 
same or different platforms. 


CAQ90s is a methodology for “platform- 
adaptive” behavior—rather than 
simply porting 
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Windows applications to 
OS/2 2.0, CA enhances them to best use 
special features of the target platform. When 

CA programs are ported to OS/2 2.0, for 
example, enhancements include 
multithreading, taking advantage of the 
Workplace Shell™, and using the System 
Object Model (SOM) object-oriented 
programming model. Marc Sokol, director of 
product strategy for CA, explains, “The most 
positive response we've heard to the 
announcement of our OS/2 product line is that 
we weren't just taking Windows programs 
and having them operate like Windows 
programs under OS/2. We are exploiting some 
of the features of OS/2.” 


CA90s gives CA the capability to migrate 
quickly from platform to platform and speeds 
the time to market by minimizing and 
isolating code that must be changed. Porting 
parts of the code to the new platform without 
changes saves time over the entire 
development cycle, reducing the time spent on 
quality assurance, testing, and so on. 


CA90s encourages developers to reuse code by 
insulating the parts of the application that 
change from platform to platform. “To best 
reuse pieces of software, before you write the 
software, think about how the pieces are going 





to connect,” advises Sokol. “For example, 
some of the obvious things are separating 
operating system dependencies or database 
access from application code. When CA 
reengineered its Windows products for OS/2, 
much of the code—even code with heavy user 
interface content—was ported without 
changes.” 


Says Sokol, “One of the first things we do, 
even with products we acquire, is to ask two 
questions: how do we 
immediately start 
integrating CA90s 
services into this 
product, and are 
there components of 
the product itself that 
could become a 
CA90s service? For 
example, CA-Textor: 
on one side, we are 
looking to make sure that 

the user interface and data access portions 
are separated from the application code. On 
the other side, we recognize that there’s a real 
value to having a Rich Text Format editing 
engine. So what we’re doing with CA-Textor, 
at the same time a lot of the other development 
is going on, is turning CA-Textor into a 
dynamic link library that can be reused by 
other components. So if CA-REALIZER or 
another development tool needs a rich text 
format editing engine, it can use it from CA- 
Textor. It’s a two way situation... as we acquire 
technology, we look at it to see how it best fits 
into those layers and how it can provide 
services we don’t already have.” 


CA9I0DS SOFTWARE 
ARCHITECTURE 


The CA90s architecture divides code into 
application code and its Common Services 
code. Common Services, available to all CA 
applications, can be thought of as layers of 
code that lie between the application and the 
hardware. As much code as possible is put 
into the Common Services layers, and all 
platform-dependent code is isolated. 


There are four layers that make up the CA90s 
architecture, as shown in Figure 3: 


e User Interface And Visualization Services 
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¢ Enterprise Software Solutions 
* Integration Services 
e Distributed Processing Services. 


Enterprise Software Solutions are CA‘s 
applications—systems management, business 
applications, and application development 
tools. The other three items are common 
services layers. 


User Interface and Visualization Services 


This layer contains the code for 
communication between the user and | 
machine. With the user-interface code located 
in a discrete layer, an application canran | 
virtually unchanged in even the most 
advanced graphical environment. The user- 
interface layer also guarantees a common look 
and feel across the CA product line. 
Conformance to a user interface standard such 
as CUA is coded only once, in this layer; 
applications can access the code as needed. 


The user interface and visualization services 
layer (shown in Figure 3) supports all major 
industry standards including CUA, Digital 
Equipment’s Network Application Support™ 
(NAS), Apple’s Macintosh, and the various 
UNIX standards. The technology, previously 
used only for CA internal development, will 
be made available in the form of class libraries 
as CA adopts object orientation for most 
products. The layer consists of four 
components: 





Figure 4: 
Integration 
Services layer 


je 
7 | 







* User IntetYact Management Services, the 
foundation of the layer, provides a 
consistent look and feel across CA products 
and platforms. 





¢ Graphics provides CA applications with 
graphics service through a single graphics 
interface. 






* Reporting provides a 
powerful and flexible 
report-generating 
engine. 


* Voice allows the 
use of voice 
technology. 


Integration 
Services 


This layer, shown in 
Figure 4, supports 
integration among CA‘s 
software products, 
increasing coordination between 
applications. It consists of five 
components: 


Figure 5: Distributed 
Processing Services layer 


* Application Services provide a range of 
high-level services such as project 
management, change control, and expert 
systems. 


“As we acquire 
technology, we 
look at it to see 
how it best fits 
into the layers 
and how it can 
provide services 
we don't already 
have.” 


Event Notification replaces the multiple 
operating systems that CA applications run 
on with a single, shared interface to the 
operating system. Event Notification 
monitors system and application events and 
shares this information among applications. 


¢ Security controls and monitors access to all 
system and application resources and 
processes. 


« Database Management Services provide 
a set of services including data 
management, sharing, integrity, 
availability, as well as high performance 
and portability. 


¢ The Repository, which provides 
centralized management for all information 
used in the computing system, is based on 
CA's advanced dictionary technology. 
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“Before you 
write the 
software, think 
about how the 
pieces are going 
to connect.” 


IBM QOS/2 Developer 


Distributed Processing Services 


This layer, shown in Figure 5, insulates CA 
applications from networking interfaces and 
protocols, Networking standards such as 
LU6.2 or DECnet are coded once within this 
layer, and CA applications are presented with 
a single networking interface. Supporting all 
forms of distributed processing across PC 
LANs, workstations, midrange, and 
mainframe systems, this layer consists of: 


* Cooperative Processing, which lets CA 
applications cooperate with each other and 
distribute processing to the most 
appropriate system. 


*. 


Distributed Database Management Services, 
which let applications access data regardless 
of physical location. 


* The Database Server, which supports 
centralized databases and client/server 
implementations. The server manages traffic 
and access and ensures data integrity. 


The Common Communication Interface, 
which insulates applications from a variety of 
networking and communication protocols. 


PORTING TO OS/2 2.0 


CA watched the OS/2 operating system from 
its inception, waiting until it was accepted by 
CA's client base before deciding to port its 
applications to OS/2 2.0. Three months after 
OS /?2 2.0's March 1992 release, CA announced 
plans to port seven major applications to OS/2 
2.0. 


Porting applications is easier for CA than for 
many software vendors because of the CA90s 
software architecture. From the beginning, 
applications are designed with porting in 
mind. Additionally, all CA developers have 
experience programming on more than one 
platform and porting from platform to 
platform. 


The general methodology is to perform a basic 
Windows-to-OS/2 2.0 port, then enhance the 
result, adding OS/2-specific features such as 
multithreading, SOM, and Workplace Shell 
support. CA divided porting tasks among 
three groups of developers, reflecting CA90s' 
division of software architecture: 





* Common Services. The CA90s software 
architecture supports multiple-platform 
applications by moving as much code as 
possible into a group of central services that 
can be used by applications across the 
product line, as with common memory 
management functions. The developers in this 
group worked on porting the Common 
Services code and converting as much code as 
possible into SOM/ Workplace Shell objects. 


Porting. The developers in this group do a 
basic Windows-to-OS/2 port, changing as 
little of an application as possible, These 
ports result in 32-bit applications that do not 
incorporate unique features of OS/2 2.0 or 
the Workplace Shell. As soon as one 
application is finished, team members move 
on to the next. 


Product Groups. These teams are 
responsible for each product; they take the 
basic 32-bit OS/2 2.0 code from the porting 
group and enhance it to utilize OS/2 2.0 
features such as multithreading. Product 
groups also add Workplace Shell support 
and turn applications into objects. 


The teams’ common goal is to create a 32-bit 
multithreaded Workplace Shell object that uses 
interprocess communications and a flat 
memory model for each application. 


While the basic port team uses UNIX-type 
tools and filters such as awk and sed to 
automate the basic port as much as possible, it 
is not a straight API-to-API port. Some tasks 
that take many calls in Windows can be done 
with one or two calls in OS/2 2.0; other simple 
tasks in Windows become more complicated 
in OS/2 2.0. In addition, many features, such 
as memory management, are completely 
different under the two systems. 


SCHEDULING 


When CA announced plans in June 1992 to port 
seven applications to OS/2 2.0, they also 
committed themselves to making demos 
available for the Fall COMDEX conference in 
Las Vegas, Nevada. This gave them only five 
months to learn OS/2 2.0 and port the code. 


As the development team had never worked 
on the operating system, team members first 





Powerful New Tools for OS/2 Programming 


The WorkFrame/2 product ... because the 
best environment for application development 
is the one you create yourself. 


With WorkFrame/2, you can integrate your choice of 
development tools — including those for DOS and Windows. 
It’s open, configurable and language independent. And it’s 
easy to customize the WorkFrame/2 interface to create your 
own development environment. 


The concept is simple. WorkFrame/2 organizes files into logical 
units called projects. By associating each project with your 
personal choice of compiler/debugger/linker/editor you can get 
the greatest productivity possible from all your development tools. 


The C Set/2 product ... because application 
development should be fast — and simple! 


C Set/2 delivers a one-two punch to help you create some of 
the fastest-performing OS/2-based applications possible. 


First, the 32-bit C compiler enables your applications to exploit 
the speed and power of 386- and 486-based computers. It’s the 
best high-performance code optimizer in the business. With the 

C Set/2 compiler, unsafe optimizations simply don’t exist. 


Second, C Set/2 comes with a fully interactive, full-function, 
source-level 32-bit Presentation Manager debugger. Just point 
your mouse and shoot, using the graphical PM user interface 
— or use the keyboard. 


Making good things happen in application development... 


Kither way it’s easy. And you'll get instant feedback on the 
screen to verify what you're doing. Debugging has never been 
so simple! 


And there’s more. The C Set/2 compiler conforms to industry 
standards — including ANSI C and [SO/TEC — and offers 
Microsoft C compatibility. With features like a full suite of run- 
time libraries and 32-16 bit linkage, you can be sure C Set/2 
will provide the function and flexibility you need to make 
application development fast and simple — the way it should be. 


OS/2 2.0 Developer’s Toolkit ... 
because it takes the right set of tools 
to build powerful applications. 


OS/2 2.0 Developer's Toolkit is the perfect companion to use 
with C Set/2. It contains a variety of language-independent 
application build and productivity tools. For the C Set/2 
compiler, ‘Toolkit provides the system linker and system header 
files. It also contains the import libraries and the NMAKE 
utility you need to dramatically increase the capabilities of 

C Set/2 to build powerful applications. 


To order or get more information on how IBM application 
development tools can work in your OS/2 environment, 


in the USA eall 


in Canada call 


1-800-342-6672 
1-800-465-7999 


IBM, OS/2, and Presentation Manager are registered trademarks, C Set/2 and Workframe are trademarks of International Business Machines Corporation. Windows is a trademark of Microsoft Corporation. 
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“Get lots of 
sleep ahead of 
time and hire 

someone to cut 
your grass.” 


IBM O5/2 Developer 


—— 





The CA team (left to right): Steve Rainess, Gregory Simeone, Danny Tom, Alex Arthur, Neil Goddard, Bar Taroogi, Patrick Howard, 


Ranjit Ramakritshnan, Gary Shattery, John Tillman, and Jacques Leisy 


had to train on OS/2 itself. For the most part, 
members were self-taught: CA provided disks 
and books and turned them loose. The 
company’s confidence was justified; in under 
three months, CA had a complete team of 
OS/2 2.0 programmers. 


CA found that it takes an average of 2 1/2 
months per product for a straight port, with 
the time required dependent largely on the 
size of the program. Other important factors 
include the time it takes to translate Windows- 
specific features and to port the segmented 
memory management code to the OS/2 2.0 flat 
memory model. 


This speed was not accomplished without a 
great deal of work. For the transfer to OS/2 
2.0, most of CA‘s team worked 65 to 75 hour 
weeks, with seven 12-to-16-hour days a week 
the norm. Developers laughingly made 
comments like “I think I’ve got a wife” and “I 
took OS/2 2.0 on a laptop to the hospital for 
the birth of my daughter.” 


CA’S ADVICE FOR PORTING 
APPLICATIONS 


CA has some advice for those considering 
porting Windows applications to OS/2 2.0: 


¢ Break the application into system-dependent 
code and application code. As much as 
possible, minimize the system-dependent 
code and maximize the application code. 


¢ Use developers with experience working on 
several platforms and porting applications 
from one platform to another. 


¢ “Have a lot of patience.” 


One developer had this to add: “Get lots of 
sleep ahead of time and hire someone to cut 
your grass.” 


CA’S OPINIONS OF OS/2 2.0 


Gary Slattery, Computer Associates’ vice 
president of research and development, 
applauds, “IBM has finally arrived with OS/2 
2.0.” The developers applauded the 32-bit flat 
memory model. Assistant vice president for 
research and development Patrick Howard 
put it succinctly: “You feel like you are back on 
a real operating system again.” 


OS /2’s 32-bit performance and protection also 
received accolades. “One false move doesn't 
bring the whole system down,” says developer 
Steve Rainess. Developers also found the OS/2 
2.0 API well thought out. Developer Danny 





Tom elaborates, “The API is a lot tighter; 
things aren't scattered around. If you know 
what you're looking for, you find it where you 
expect it. It’s clearer how things work.... 
Concepts are clearer.” 


The CA developers appreciated the Workplace 
Shell and the SOM programming model. 
Developer Jacques Leisy calls the Workplace 
Shell “another step up from Windows and the 
Presentation Manager™ in the evolution of 
graphical user interfaces.” Both Leisy and 
teammate Neal Goddard agree that the object- 
oriented paradigm used in SOM and the 
Workplace Shell helped them move code from 
the application code to the Common Services 
code. 


Many CA developers think the OS/2 2.0 
versions of their applications will be better 
than the Windows versions for several reasons. 
“First of all, you’re not shipping applications, 
you're shipping objects,” says Leisy. Satisfied 
developers also mentioned OS/2 2.0’s superior 


The world's 


best software 


for testing 
networked 
PM applica- 
‘tions now 


stands alone. 


Winter 1993 


performance and the addition of drag-and- 
drop capability within the application. Overall, 
CA developers are enthusiastic about OS/2 2.0 
and about developing applications for the new 
operating system. Concludes Leisy, “After 
people work on OS/2 2.0 for a while, they tend 
to fall in love with it.” 





Eric Nelson, JBM Corp., Information 
Development, 1000 N.W. 51st St., Boca Raton, 
Fla., 33431. Nelson has worked for IBM for almost 
two years and is currently working on the OS/2 
Toolkit and Technical Library. This ts his first 
article for OS/2 Developer. Nelson holds a B.A. 


from the University of Texas. 


Testing that keeps up with development. 
Higher quality software. 

That's why hundreds of QA 

engineers and developers use 

the Automated Test Facility 

to test their networked 

Presentation Manager and 

Windows apps. 


ATF NetWorked 


Both ATF NetWorked and Softbridge's new ATF 
WorkStation were built to stand up to the complexities 
of testing a graphical user interface like PM. 


To find out how ATF can 
help you meet the challenges 
of testing PM apps, call: 
800-955-919 0. 





_—\] Softbridge, Inc. 
125 CambridgePark Dr. 
Cambridge, MA 02140 
617-576-2257 (Phone) 
617-864-7747 (FAX) 


ATF WorkStation 











Figure 1: Application-to-device driver interface 
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Designing An OS/2 


Device Driver 


by Steven Mastrianni 


The following is an excerpt from the book Writing 
OS/2 2.0 Device Drivers in C, reprinted with 
permission of Van Nostrand Reinhold. 


To successfully design an OS/2 device 
driver, a developer must understand 
the device driver's role and have a 
solid working knowledge of the OS/2 
operating system and design 
philosophy. Debugging a device driver 
can be difficult, even with the proper 
tools. The OS/2 device driver operates 
at Ring 0 with full access to the 
system hardware. However, it has 
access to almost no OS/2 support 
services except for a handful of DevH1p 
routines. As many device driver 
failures occur in a real-time context 
(for example, during interrupt 
handling), it may be difficult or 
impossible to find a problem using 
normal debugging techniques. In such 
cases it is necessary to visualize the 
operation of the device driver and 
OS/2 at the time of the error to locate 
the problem. 


THE BASICS OF 
DRIVER DESIGN 


| device driver receives two 
basic types of requests, those 
that can be completed immediately and those 
that cannot. It receives these requests via a 
standard data structure called a request 
packet. The device driver manipulates request 
packets with the Device Helper or DevHLP 
routines, as in Figure 1. 





Requests that can be completed immediately are 
handled as they come in and sent back to the 
requestor. Those that cannot be handled 
immediately, such as disk seeks, are queued for 
later dispatch by the device driver. Disk device 
drivers usually sort pending requests for disk 
seeks in sector order, thereby minimizing disk 
seek time. 


The OS/2 device driver plays an additional 
role in system performance and operation. 
When a device driver is called to perform a 
request that cannot be completed immediately, 
it Blocks the requesting thread, relinquishing 
the CPU and allowing other threads to run. 
When the running request is completed, the 
thread is immediately UnBlocked and run. The 
device driver then queries the request queue 
for any pending requests that may have come 
in while the thread was blocked. When an 
application calls a device driver, the 
application's local descriptor table (LDT) is 
directly accessible by the device driver. 


There are two types of OS/2 device drivers, 
block and character. Block device drivers are 
used for mass storage devices such as disks and 
tape devices. A character device driver such as a 
modem or serial terminal is used for devices 
that handle data one character at a time. OS/2 
device drivers can support multiple devices, 
such as a serial communications adapter with 
four channels or a disk device driver that 
supports multiple drives. 


OS/2 device drivers receive requests from the 
OS/2 kernel on behalf of an application 
program thread. When the device driver is 
originally opened with a DosOpen API call, the 
kernel returns a handle to the thread that 
requested access to the device driver. This 
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IBM Extended Extend your 
Services | 


ahye reacn. 


Tap into the power of OS/2” with flexible 
communications, versatile connections 
and a sophisticated database. Extended Services enables you 
to view your data, communicate with outside information 
services and record transactions all at the same time. 

Together Communications Manager, Database Manager 
and Query Manager make up the components of Extended 
Services. Distribute your data and processing tasks among 
workstations, departmental systems and hosts. The 3270 
EHLLAPI interface now allows multiple, simultaneous 
access by applications; these functions can now be used 
in REXX Procedure Language Programs for 3270 and 
9250 applications. Virtual Device Drivers (VDDs) allow 
NETBIOS applications, running in DOS partitions, to 
share an adapter with other DOS and OS/2 NETBIOS 
applications. Existing DOS 3270 EHLLAPI applications 
can run in a DOS partition, sharing Communications 
Manager EHLLAPI with other DOS and OS/2 applications. 

Enhancements to the Communications Manager include 
improved APPC support — with simplified configuration 
and improved performance, most notably on a Local Area 
Network (LAN). You can now use long file names for file 
transfers! You'll see an increased number of simultaneously 
active workstations through a SNA gateway and better 
SNA gateway LU pooling to improve session accessibility. 

The Database Manager allows existing DOS and DOS 
Windows™-based machines to become database clients on 
a LAN. Enhanced SQL capabilities bring the database into 
closer compliance with SAA™ SOL Level I. Roll-forward 
recovery (archive logging) reduces the need for manual 
recovery if your system fails. 

OS/2 Extended Services lets you issue SQL statements, 
database environmental commands and utilities directly 
from the OS/2 command line. You'll access, update and 
administer data without having to learn the SQL syntax, 
or download, import and convert DB2® and SQL/DS™ host 
data. You can also use the comprehensive set of database 
administration tools and facilities, including roll-forward 
recovery and First Failure Support Technology/2 (FFST/2). 
OS/2 ES lets you log error information needed for problem 
resolution, helping you to minimize the possibility of 
running into the same error again. 


Put IBM software to the test! | SOO IBM-CALL. 








More Power. 


* Contains integrated communications and database 
manager functions of OS/2 EE and of SAA Networking 
Services/2, helping you manage information and move 
it with ease. 

® Provides multiuser database functions with Database 
Server for OS/2. 

e Extends communications and database functions co 
selected non-IBM hardware platforms and to selected, 
compatible OS/2 operating systems. 

e Provides multinational solutions for your expanding 
global business needs with twelve versions including 
U.S. and U.K. English. 

e IBM SAA Distributed Database Connection Services/2 
Program allows a Database Manager client to access 
DB2, SQL/DS and OS/400® databases on $/370, S/390™ 
and IBM midrange AS/400® computers. 
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| ons Tools System Exit 
Databases 


Open New Database 
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Comment 


_Cancel | Help | 
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With 0S/2 ES you get industrial-strength function supported by a rich 
array of tools. 


To help better serve your needs seven new productivity 
aids are shipped with Extended Services. Included are print 
and file transfer utilities, a keyboard utility, a problem 
determination tool, APL support and a database perform- 
ance optimization tool. A new publication describing these 


applications is shipped with Extended Services. 


Would you like to order OS/2 2.0? 


Here's how! Call: 

Corporate accounts and invoice orders 1 800 IBM-CALL 
“Credit card orders 1800 3IBM OS2 
In Canada 1800 465-7999 


il Get a leg up on 
Common User 
Access Controls | OS/ py code. 

Libra ry/2 Save your energy for the really creative 
parts of your work and let one of IBM’s 
newest products, CUA Control Library/2, provide the 
interface for GUIs. Whether you're writing for Windows 
or OS/2 applications, it’s all right here for you. 
¢ Offers abilicy to conform to CUA 91 architecture for 
Notebook control, one of seven tools within CUA Control Library /2. OS/2 V1.4 and Windows V3.0 and 3.1. 
¢ Provides for easier application migration to OS/2 V2.0 

because the CUA Controls APIs for OS/2 V1.3 and 


IBM ( | The right tool Windows V3.0 and 3.1 are consistent with rhose 


Developer's found in OS/2 V2.0. 


Wor Sef / ? for your job . * From containers to sliders, files co notebooks, fonts to 


value sets, CUA Controls Library/2 does it all. 








The OS/2 2.0 Application Development 
} Tools can help to make your program- 
mers more efficient, more precise and more productive. 
These tools work well individually or together to provide 
a complete 32-bit C-language environment so you can 
develop a full range of applications — from retail to 
mission-critical, For the greatest convenience choose a 
packaged solution. The IBM C Developer's WorkSet/2 kit 
bundles the Developer's Toolkit and WorkFrame/2 with 
the C Set/2 — providing a total application development 
ere for OS/2. 
Takes advantage of the power of 80386- and 80486- 
based system units through state-of-the-art code 
optimization. 
¢ The OS/2 2.0 Developer's Toolkit provides a compre- 
hensive set of language-independent tools and code 
samples fundamental to building advanced OS/2 2.0 
applications. 
¢ IBM OS/2 2.0 Technical Library supplements the 
Toolkit with programming guides and other printed 
references. 
* IBM WorkFrame/2 makes application development 
easier by organizing projects and allowing you to 


integrate your preferred tools. 63 % *s, avin M4 bs I 


a SESE eevee Seomins Are cutee we apie Ws Get C Developer’s WorkSet/2 by 


its runtime libraries and a fully integrated, source level 


Presentation Manager™ debugger. April 6, 1993 for only $370. 












The Prolog to 


Prolog/2 your logic. 


IBM SAA AD/Cycle Prolog/2 is a high- 
productivity, logic-based programming 
language for OS/2. With its powerful logic expressions 
and inferencing technology Prolog/2 is ideally suited for 
developing complex logic applications. Applications devel- 
oped for OS/2 using Prolog/2 can easily be ported to the 
System/370 environment. 

* A programmer using Prolog develops a logically consis- 
tent description of the problem. When Prolog executes 
the application it implicity controls the logical path to 
the solution. 

« Provides interactive programming, a fast interpreter and 
a full sec of built-in functions. 

¢ Enables application developers to rapidly create proto- 
types. An initial prototype provides the basic structure 
of the final operational application. 

¢ Prolog development features provide a unique application 
development environment combining object-oriented 
programming facilities with logic programming. 


US Host power on 
AD/Cycle 


* 

Wwe a workstation. 
Package/2 With the new IBM SAA AD/Cycle PL/I 
@ Package/2 you can develop applications 
ona  workéecation targeted for a S/370 host or OS/2. You can 
enjoy the higher productivity and lower cost benefits of a 
workstation with programs developed in an OS/2 environ- 
ment, including editing and compiling. 

« Provides a common PL/I development environment on 
OS/2 and $/370. 

e Allows for Local Area Network (LAN)- based applica- 
tion development, linking multiple PC workstations. 

¢ §/370 PL/I applications can be readily ported to OS/2 
Version 2.0. 

¢ Programmer skills in PL/I can now be carried to the 
OS/2 operating environment. 
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PL/I Package/2 lets you develop $/370 and OS/2 applications on 
your workstation. 


APL? A 
Auta A new symbol 


Mie for productivity. 


APL2™ ts an extremely effective pro- 
gramming language in a wide range of 
uses from interactive computing to “what if” modeling, 
exploratory programming and application program design. 
Completely revised for 1992, APL2/PC provides high 
compatibility with the 370/390 mainframe and RISC 

System/6000™ APL2 products. APL2/PC permits transpar- 

ent import/export of programs and data via the IN and 

OUT commands, and allows for a high degree of connectiv- 

ity with APL2 on the host and RISC platforms. 

« Two interpreters are included: 16-bit and 32-bit. 

« Workspace sizes of over 30MB are supported on 386, 
386SX and 486 machines. 

* Full-screen editor/debugging facility. 

* APL2 screen and printer fonts are included. 

¢ APL2 Application Packaging facility allows users to run 
previously developed APL2 applications as a standalone 
executable module. 

e APL2/PC provides many of the Auxiliary Processors 
available with APL2/6000 and/or host APL2 products: 
host system commands, stack, full-screen management, 
universal graphics, file I/O and common object library 
management. 

« Facilities for host-system and LAN communications. 
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Commands playing back 


Fast, flexible os | 
— | 
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Interactive 
Test Too! 


The Workstation Interactive Test Tool 

easily automates many of the tasks 

associated with interactive application testing. It’s cost- 

effective, too! Customers have realized 50-70 percent 

Savings In regression test time. 

* Test both host- and workstation-based applications. 

* Create test cases as you go, recording keystrokes or 
mouse movements. 





Create, analyze ond playback test cases /scripts automatically with 
Workstation Interactive Test Tool. 


It’s all in the 
translation. 


IBM SAA AD/Cycle Translation- 
Manager/2 helps you, as a professional 

or occasional translator, translate from a selected national 
language into another national language. Ir allows you to 
address translation more effectively in the early stages of 
application development. Regardless of the size of your 
environment, TranslationManager/2 will support you 
through the entire application development process, start- 
ing with terminology created at the requirements gathering 


Improved quality. 
stage, through translation of documentation and program- 


Increased pation An ps 
integrated text, and maintenance of this textual information. 
productivit y. « Provides enhanced business solutions by support of 


Improve your application development productivity with 
the Software Analysis Test Tool. This tool helps you — the 
developers, testers and maintainers — discover how well . 
your application has been tested. 

Software Analysis Test Tool is a key component in im- 


IBM 

¢ Save and compare screens and/or areas within screens. WAG Ta 

e Use your own editor to tailor already recorded test cases. 

e Add logic to your test cases by imbedding Procedures 
Language 2/REXX commands. 

¢ Watch your test cases playback or run them at night on 
your display in unattended batch mode. 

¢ Measure performance of key functions by inserting time 
stamps. 


Translation- 
Manager/2 
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translation, as an integral part of developing an appli- 
cation, or in standalone mode outside of the AD/Cycle 
environment. 

Increases productivity with a variety of convenient and 
powerful translation, dictionary and linguistic support 
functions. 


proving application development productivity. It provides « Reduces systems management complexity and increases 
complete testing analysis, graphical display of test case operational productivity of the total translation process. 
coverage, animation of test case execution and online ¢ Integrates previously created translation and dictionary 
documentation, files. Translations obtained previously by using Trans- 


lationManager/2 can be reused and adapted through 
the Translation Memory function. 


« Provides a graphical display of the execution flow of 
your program. 
¢ Offers a selection of program metrics to evaluate testing 
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coverage. Order sa laforeiation 
« Supports IBM languages in the runtime environment. Program No. OTC 
¢ Supports interactive browsing, query and reporting of $696,308 ADK Runtime Facility $420 
test coverage information. F/C 0995 Development Facility Feature $5,250 
+ Helps you test, maintain, measure and analyze the ‘FC 1016 Runtime Extension Feature $336 
lity of existing and newly produced software with BAG LORS, Eplrsiegenecs Babi ty: Eeretion Roatse ring 
ee ee yP 5601-388 PL/I Package/2 $2,730 
graphical displays for a clean system and structure view. 5799-PGG APL2 for the IBM PC $630 
5601-442 Software Analysis Test Tool $6,305 
5601-441 Workstation Interactive Test Tool $2,520 
5621-327 TranslationManager/2 $5,250 
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Turn your PS/2 or PC into an applica- 





CICS OS/2 lets you use the programming workstation as a 

development plattorm, bringing flexible scheduling to your 

department while capitalizing on existing CICS program- 

ming skills. This powerful environment offers the portable 

EXEC CICS command level Application Programming 

Interface in the COBOL and C programming languages 

and allows you to develop and test your applications. Many 

production applications can be produced in their entirety 

on a standalone workstation. 

« CICS OS/2 provides local transaction processing with 
or without host attachment. 

* Expanded communication support tor SAA allows you 
to capitalize on your investment in OS/2 EE. 

¢ Developers can take advantage of techniques like Ad- 
vanced Program-to-Program Communications (APPC) 
without learning APPC coding. 


ts ua Platforms at 
ntegrated 
your request. 


Enhance your applications with expe rise 


Reasonin 
shell 





| using The Integrated Reasoning Shell® 

(TIRS™), a tool that provides application developers with a 

productive development environment and high performing, 

compiled applications. Multiplatform support provides you 

with the flexibility to deliver applications where they are 

needed. 

* Provides advanced artificial intelligence (AI) function 
for development of many business application types. 

¢ Includes a powerful Knowledge Representation 
Language. 

« Offers compiled applications for fast runtime 
performance. 

¢ Provides portability to multiple platforms, including 
selected SAA environments for flexible growth. 

e Enhances developer productivity with mouse-assisted, 
graphical development interface under OS/2. 

* Improves performance using a runtime subsystem 
architecture for CICS and IMS. 

« Uses direct interlanguage communication. 

* Includes sample knowledge bases to assist application 
developers in learning TIRS. 


| S00 IBM-CALL. 
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More Action. 


tion powerhouse with CICS OS/2™ V1.2. 








« Offers automatic transfer of applications from work- 
station co host. 


» Works under OS/? and C Set/?. 
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TIRS provides an interactive windowed graphic interface for creation 
and maintenance of knowledge bases. 


Pin Define, test and 
view. 


As part of the IBM SAA Cross System 
Product Set, CSP/2AD Version | helps 
you develop high-quality applications faster and easier. 
CSP/2AD runs under OS/2 and provides a highly produc- 
tive environment for defining and testing Cross System 
Product applications for OS/2 and MVS. It has an easy-to- 
use graphical interface that conforms to the Common User 
Access architecture. Application components can be viewed, 
accessed and modified using a graphical representation of 
the application, simplifying both development and main- 
tenance. Finally, you can use the interactive test facility to 
completely test an application on the workstation prior to 
generation. Additional features include: 
« Statement templates and interactive syntax checking. 
¢ The ability to monitor application execution during 
testing, watch and modify data values, set breakpoints, 
modify application logic and continue testing. 
« Source level debugging. 
* Urcilities to transfer applications to the IBM SAA Cross 
System Product/370 Application Development product 
for generation. 
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Enhanced graphical applications are yours with EASEL Workbench. 


wa Powerful 
Workbench 
F arieanas 


lopment. 


Easel Corporation’s EASEL Workbench® provides a robust 

set of tools for developing client/server applications. Easel 

customers are achieving success by using EASEL Work- 

bench to rapidly prototype and deliver a wide variety of 

sophisticated business solutions for OS/2, Windows and 

DOS. A variety of client/server architectures are supported 

by EASEL Workbench applications, including transaction 

processing and DSS applications that access local and 

enterprise data via SQL or other methods. 

¢ Lets developers build SAA/CUA™ applications. 

¢ Provides key component for AD/Cycle Analysis/Design 
and Generator strategies. 

* Leverages power of OS/2 development platform. 

* Compiles and executes for OS/2, Windows and DOS 
environments. 

¢ Provides incremental compiler, source level debugger 
and trace facilities and organization tools to manage 
development environment. GW 


A server-based 
repository. 


The InfoSpan™ Repository Management 
System (IRMS™) by InfoSpan Corpora- 
tion 1s the industry's first ANSI/FIPS Information Resource 
Dictionary System (IRDS) conforming repository. IRMS is 
a comprehensive LAN server-based system. IRMS is the 
foundation for InfoSpan's CASE and Reverse Engineering 
Tool Integration solutions. It is enabled to IBM's AD/Cycle 





Ose 
Repository 


Management 
System 





Platform Services and Information Model. Subsets of IBM's 

Information Model are offered on IRMS. 

* Offers a single design with a common user interface, 
single-user and multiple-user versions. 

* Includes tool services to build custom data dictionaries 
to administer data and standardize data elements. 

« Provides solutions for information resource and asset 
management, software design and change management. 

¢ Supports standardization of data elements that need 
aliasing, data attributes and approval management, all 
by means of custom naming policies. 

IRMS Repository Management System tools include 
Repository Manager, IRMS Repository Modeler & Proro- 
typer, Graphical Repository Browser & Navigator, Report- 
ers & Analyzers, Graphical Repository Administrator, Data 
Element Policy Defines and Administrator, and Repository 
Loader, Ga 
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Program No. OTC» 
5688-101 CICS OS/2 $810 
The Integrated Reasoning Shell 





5621-003 TIRS Development/? 
5621-004 TIRS Runtime/2 
5688-205 ‘CSP/2AD Version 1 
EASEL Workbench Tools 
5758-ECO EASEL/2 Workbench with Production Compiler 
5758-EC1 EASEL/2 Workbench Migration from IBM EASEL ~ 
5758-EC4 Additional EASEL/2 Production Compiler : 
37 58-EC7 EASEL/2 Runtime System 
InfoSpan Repository Management System* 
5758-IFC Repository Manager 
5758-IFD Modeler & Prototyper 
5758-IFE Browser & Navigator Manager 
37 58-IFF Reporter & Analyzer 
5758-IBG Graphical Reporter & Analyzer 
5758-IFH Graphical Repository Administrator 
5758-IFI Name Administrator 
af 58-IFL Repository Loader 
* Quantity discounts and multiuser package prices are available. 





Save up to 20% 


on additional licenses. 
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More cae 


Micro Focus 


as This workbench 
Tete Comes with a 
toolset. 


Micro Focus” COBOL™ Workbench is an integrated 
collection of programming productivity tools that comple- 
ment the Micro Focus COBOL compiler. It provides a 
highly integrated and responsive development environment 
that can dramatically improve programmer productivity. 
The function and design of the COBOL Workbench envi- 
ronment allows you to quickly address your application 
backlog, produce efficient and higher quality applications 
and effectively maintain COBOL applications on a single 
PS/2. These applications can be targeted to a wide range of 
host and PC environments. Key functionality in the Micro 
Focus Workbench includes; 

« Full-screen text editor 

e Mainframe COBOL Compatibility (IBM OSVS, VSC2, 
DOSVS, COBOL 370) 

* EBCDIC data file support 

« Source Code Level debugging with ANIMATOR. 

The cost benefits of using the Micro Focus Workbench 
for mainframe development are: 

* Consistently fast response times 

* Saves mainframe cpu cycles 

* Reduced TSO charges 

* Dedicated development environment for the program- 
mer on the PS/2. 

Add-on products that complement the Micro Focus 

COBOL Workbench: 

* Micro Focus CICS Option™ provides mainframe CICS 
Command level compatible application development 
environment. 

* Micro Focus CICS OS/2 Option™ is a full-function IBM 
CICS multiuser, multitasking environment. 

*¢ Micro Focus IMS Option™ provides a mainframe com- 
patible IBM/DB and DC development environment. 

*¢ Micro Focus IMS Production Option™ is a multiuser 
execution environment. 

e Micro Focus 370 Assembler emulates 370 mainframe 


assembler on the PC. EE 
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Micro Focus COBOL Workbench supports effective and efficient 
development that can improve productivity. 


A model 


performance. 


Bachman 


BACHMAN 
Development 


Tools 


This easy-to-use product set by 
Information Systems, Inc. provides you 
with the ability to do model-driven development either of 
new applications or from your existing investment in 
database designs. With Bachman tools both analysts and 
programmers will see a decrease in their work effort as well 
aS an improvement in application quality. 

¢ BACHMAN/Analyst™ produces models that can be 
forward engineered to production-quality DB2 or 
SQOL/DS systems. 

¢ BACHMAN/Capture™ products allow IS departments 
to take full advantage of data designs residing in 
existing database structures. 

« BACHMAN /Database Administrator™ (DBA) optimizes 
large DB2 designs and DB2 objects. It provides re- 
engineering capabilities wich business models. 

« BACHMAN/Designer™ generates external source format 
optimized for IBM’s Cross System Product application 
generator. 

* BACHMAN/Shared Work Manager allows many 
analysts to work concurrently on an enterprise model. It 
lets you create subset assignments for different analysts, 
monitor and view their work in progress and reassembles 
their submodels into a finished enterprise model. 

* BACHMAN/DBA Enabler allows the database adminis- 
trator to design better performing databases for SQL/DS. 
LCSP) 
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Redevelop your aging, complex systems into modern, leading-edge 
systems with VIASOFT’s Existing Systems Workbench. 


Put new life in 
old programs. 


IS professionals, empower yourselves 

| with an integrated set of tools that 
effectively enhances, maintains and redevelops aging 
applications. Using VIASOFT, Inc.'s Existing Systems 
Workbench management you can gain control of existing 
systems; programmers can understand and improve aging, 


Tan 


Existing 


Systems 
Workbench 





complex systems; and analysts can extract business rules 

from existing applications and reuse them in new systems. 

The OS/2 workstation tools mentioned below work in 

conjunction with their respective host products. 

* Using VIA/Insight 2 and VIA/SmartDOC2, application 
programmers can significantly decrease the amount of 
time they spend understanding the legacy code of the 
business enterprise. 

*« Using VIA/Renaissance2, programmers can turn large 
programs into smaller, easier to manage and understand 
module programs. 

e Using VIA/ReCap2, programmers can quickly measure 
the complexity of an application, including Function 
Point measurement, e¢ach time the application is 


changed. BE 





Solutions today. 


Knowledge Ware® builds, markets and 
supports CASE tools for developing 
high-quality, well-documented business 
applications for multiple platforms. 
Knowledge Ware's extended family of products, including 
the Application Development Workbench (ADW), main- 
tains and enhances current software applications. 

ADW is composed of a highly integrated, graphics- 
based set of workstation software, supplemented by optional 
mainframe-based tools. The ADW products aid users in all 
phases of application development: 


os 
Development 


Workbench 
tor 0S/2 








* Planning and Analysis « Code generation 
* Prototyping e Systems documentation 
© Design * Maintenance. 

ADW lets users put the focus on defining and solving 
organizational needs. For instance, developers can gather 
application requirements independently, then generate code 
for applications running on mainframe, midrange and PC 
hardware. This integration strategy means developers can 
use and reuse design logic across all platforms. 

The family of ADW products includes ADW/Planning 
Workstation, ADW/Analysis Workstation, ADW/RAD 
Workstation, ADW/Design Workstation, ADW/CSP En- 
ablement Facility and ADW Documentation Workstation. 


CSP) 
Ordering Information 
Program No. OTC 
Micro Focus COBOL Workbench 
5758-MFF Micro Focus COBOL $750 
9758-MFH CICS OS/2 Option $1,250 
5758-MFI CICS Option $1,250 
5758-MFK IMS Option $1,250 
5758-MFM 370 Assembler $1,250 
5758-MFA COBOL Workbench $2,500 
Complementary Micro Focus COBOL Workbench products 
5758-MFB CICS OS/2 Option $3,500 
5758-MFC CICS Option $3,500 
5758-MFD IMS Option $3,500 
5758-MFE CICS and IMS Option $4,500 
BACHMAN Development Tools 
5758-BAA Analyst $10,000 
$758-BAB Capture for IMS $10,000 
5758-BAC Caprure for COBOL $ 5,000 
5758-BAD Capture for PL/I $ 2,500 
5758-BAM DBA $15,000 
5758-BAU Designer $10,000 
5758-BAV DBA Enabler $15,000 
5758-BAW Shared Work Manager $5,000 
VIASOPT Existing Systems Workbench 
5758-VSH VIA/Insipht2 $2,500 
5758-VSJ VIA/Renaissance2 $3,000 
5758-VSL VIA/Recap2 $1,500 
5758-VSN VIA/SmartDoc2 $1,000 
Application Development Workbench 
5758-K31 ADW/Planning Workstation $10,750 
5758-K32 ADW/Analysis Workstation $10,750 
§758-K33 ADW/Design Workstation $10,750 
$758-K34 ADW/RAD Workstation $10,750 
5758-K35 ADW/Documentation Workstation $10,750 
5758-K26 ADW/CSP Enablement Facility $ 1,100 
5758-K30 ADW/REF $25,000 
§758-K36 ADW Starter Kic* $24,500 


*One each: Planning, Analysis, Design, CSP Enablement Facility, RAD 
and DOC Workstations. Available to new accounts only. Limit one per 
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BM 05/2 Good news 


ween travels fast. 


Why settle for software that just lets 

you share files, printers and applications? 

IBM's OS/2 LAN Server 3.0 includes new functions that 

provide greater reliability, faster access to data and increased 

security for your resources and data. 

With OS/2 LAN Server 3.0, DOS (including DOS/ 
Windows support) and OS/2 requesters can easily access 
LAN resources, no matter where they are located. Even 
remote resources appear to reside on end-user workstations. 
This single-system image is achieved through advanced 
administrative facilities called Domains and Aliases. They 
allow users to access resources that reside on other OS/2 
servers — or even Microsoft? LAN Manager servers — 
with a single network logon. 

As a result, users can transparently access and share 
directories, files, disks, printers and programs, plus serial- 
ly attached devices such as plotters, modems and scanners, 
Also, administrators can more easily make changes in re- 
source locations, security rights and user accounts. 

OS/2 LAN Server 3.0 1s available in two configurations 
— Entry and Advanced. 

« Brings you High Performance File System (HPFS) for 
i386™ and 1486™ processors, which speed access to 
server data. 

* Provides support for up to four LAN adapters. 

* Includes Remote Initial Program Load (RIPL), which 
supports diskless DOS and OS/2 workstations, enhances 
security and allows you to control application levels. 

¢ Gives UPS support to keep the server running in case 
of power failure. 

* User Profile Management (UPM) provides a graphical 
interface for administration of user's assigned resources. 
The LAN Requester distributed feature of OS/2 LAN 

Server 3.0 gives you the OS/2, DOS and DOS Windows 

Requesters. Each distributed feature can give you simulta- 

neous access to multiple servers, increasing the flexibility of 

your network. The OS/2 LAN Server 3.0 package includes a 

license for one LAN Requester feature. For each additional 

feature you order, you may make a single copy of the LAN 

Requester and we will send you a proof of license certificate. 

This allows you to order just as many LAN Requesters as 

you need. 


Put IBM software to the test! 1 SOO IBM-CALL. 
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Manage token ring and broadband networks with LAN Manager. 


A The most 
Network 


tings Management for 
your LAN. 


Whether you manage your LANs locally from a workstation 
or centrally from NetView® you can do it more efficiently 
with this LAN management tool. Running alongside your 
other applications on O$/2 EE, this application allows you 
to manage multisegment token rings, broadband and base- 
band PC Networks, as well as IBM LAN Bridges. 

If you have a remote single-segment IBM Token-Ring or 
PC Network and want to integrate it with NetView, IBM 
LAN Network Entry lets you do it. Running as a task in 
OS/2 EE, this software uses Communications Manager to 
communicate with NetView via an existing LAN SNA 
gateway. It provides a subset of the expanded set of 
NetView commands supported in IBM LAN Network 
Manager 1.1. 
® Identifies and records network errors, access failures 

and LAN workstation adapter failures. 

* Automatically maintains detailed configuration infor- 
mation about network devices and their locations. 

* Communicates with che host via an existing LAN 
gateway or over a Synchronous Data Link Control 


(SDCL) link. 






LAN Wide 


Area Network to WAN. 


Connect remote LANs to your SNA 

or X.25 backbone — and expand LAN 
applications without having to duplicate teleprocessing 
lines. This program allows IBM Token-Ring Network, 
IBM PC Network and Ethernet LANs to communicate 
with each other over a wide area network using NETBIOS 
to NETBIOS flows. Ideal for small LANs that need access 
to servers on a small number of “hub” LANs. It will grow 
with you to support large LANS in complex networks. 
Anywhere your SNA network goes you can have NETBIOS 
connectivity available. 

¢ Provides full 802.2 and LU 6.2 support. 

¢ Eliminates need for dedicated processors. 

¢ Sends alerts to a host via LAN Manager. 


PT Now 


Installation | 


Utility/2 installation’s 
easier. 


Need help with installation? The IBM LAN Installation 
Utility/2 (LIU/2) is an aid in the installation of OS/2 2.0, 
Extended Services 1.0 and LAN Server 2.0. With this 
program these systems can be installed simultaneously 
with little effort and time. Working on a redirected drive 
replication philosophy, the IBM LAN Installation Urility/2 
eliminates the need for the insertion of the multiple 
diskettes images at the target workstation. All of the new 
operating system and subsystem code resides on a server 
drive that is accessible to the target machine by a redirec- 
tion facility. 

That’s not all — LIU/2 can be used to deliver any 
customer-defined package of files, including applications, 
to any target machine. 
¢ Creates a common software image on a source machine, 

and sends it to the LIU/2 distribution server. 

* On the distribution server, builds customized files for 
each target machine and produces two boot diskettes for 
each target machine. 

* At the target machine, the boot diskettes are loaded and 
LIU/2 installs OS/2 from the distribution server without 
any furcher human intervention. 









Anywhere your SNA network goes you can have NETBIOS connectivity. 


IBM LAN 
yr ne At your 


Utilities/2 service. 


Desire’ for the enterprise server/ 

requestor environment, this set of OS/2- 

based services includes applications for configuration, 

performance and fault management. It also includes the 

command/data transport applications required to use them. 

¢ A graphical display provides a display of LAN stations 
and their status, panel-driven commands and notification 
of alert conditions. 

* Includes a transport method by which system manage- 
ment applications can be invoked remotely and system 
management data can be sent to a central collection 
point. 

* Includes a set of IBM-supplied LAN system management 
applications and software to maintain an OS/2 database 
that contains the response information from the IBM- 
supplied management applications. 
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Wi} Move up to 


Personal 


Communications multiple Ssesslons. 
/32]0 2 : 
your users need multiple concurrent 
host sessions — or multiple DOS ses- 
sions with native Windows support — here's your answer. 
IBM Personal Communications/3270 Version 2.0 provides 
advanced host communications and gateway services for 
PS/2s and PCs. It offers both a DOS mode with enhanced 
workstation function, a Windows mode and a gateway 
mode all in a single package. 
¢ Host connectivity via SDLC, Token Ring, Ethernet, 
3270 Distributed Function Terminal (DFT) and Control 
Unit Terminal (CUT) and asynchronous connections. 
* Provides enhanced fonts for easy-to-read screens. 
e Facilitates the management of large installed bases via 
a quick installation option. 
« Allows users to move from DOS to Windows or gateway 
mode without having to buy an additional package. 


Emulate ASCII 


Nd on your PC. 


Emulator 





IBM Muli: 


Terminal 


If you're looking for a way for your PS/2 

workstations to concurrently emulate 

inlinle ASCII terminals, IBM Multi-Terminal ASCII 

Emulator/2 is the answer. It allows you to centrally emulate 

multiple asynchronous terminals on a single workstation — 

alleviating the need for unique consoles for devices in the 

system and consolidating their monitoring to a single 

workstation. You can centralize access to the ASCII operator 

terminals because of this program's key support of LU6.2 

connections. 

¢ Enhances systems management by providing central site 
access to non-SNA devices and management systems 
within an SNA network. 

¢ Protects your investment by expanding central site 
support into the non-SNA portions of the network. 

¢ Enhances network support personnel productivity by 
improving information via direct access to non-SNA 
portions of the network. 

¢ Enables growth and migration in a heterogenous 
network by allowing management access as the initial 
step to total management integration. 





We ll tax you product specs, | SOO IBM-CALL. 









More Access 








Move up to multiple-session 3270 emulation for DOS and Windows 
environments with Personal Communications /3270 V2.0. 


IBM 
Networking Protect your 


Services investment. 


Networking Services/DOS lets you 
integrate existing DOS and Windows 
wrorkstariong into your computing network, From small 
workstations to the largest mainframe system, Networking 
Services/DOS allows DOS and Windows workstations to 
participate in networks with both IBM and non-IBM 
systems. 

That's not all. Networking Services/DOS lets you bring 
your DOS workstations into a distributed computing envi- 
ronment. This type of distributed computing combines the 
control, speed and storage capacity of large systems with the 
usability and flexibility of inexpensive DOS workstations. 
¢ Provides a low-memory Advanced Program-to-Program 

Communication solution for DOS and Microsoft 

Windows environments, 
¢ Allows you to effectively develop and run distributed ap- 

plications for the DOS and Windows environment, since 

Networking Services/DOS can run in as little as 9OKB of 

conventional memory, plus the required 50 to GOKB of 

memory when communication applications are run. 

* Uses CPI-C, a consistent programming interface for 
distributed applications throughout the networks and 
aids portability of applications and programming skills. 

* Provides easy integration into dynamic APPN networks, 
as well as existing SNA subarea networks. 
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0S/2 TCP/IP with X-Windows helps you broaden your connections. 


IBM TCP/IP Make the night 


Connection 


fi connection. 


Widely used in government, academic, 

| engineering/scientific and commercial 
environments, TCP/IP protocols allow you to network with 
the most commonly used workstations and hosts — IBM 
and non-IBM — including UNIX® systems. Because IBM's 
family of TCP/IP products is so extensive, users can inter- 
operate with other systems in these networks — whether 
they are running DOS, Windows, OS/2, OS/400, AIX® 
VM™, MVS™ or software from vendors such as Sun® DEC® 
HP® and Apple® 

TCP/IP Version 2.1 for DOS supports TCP/IP in DOS 
or Windows Mode. TCP/IP for OS/2 supports OS/2 systems 
and is integrated for use with the Presentation Manager. 
Both products interoperate with Novell® and IBM LAN 
requestors so that you can use TCP/IP applications at the 
same time that you are using your local servers. 

Both products support the most popular LAN environ- 
ments — Ethernet and Token-Ring. They also can be used 
with serial lines including dial up. The OS/2 product also 
has an optional kit that supports X.25 networks so that 
you can use both public or private X.25 networks. 

A full suite of TCP/IP applications is included with 
the base kits for the DOS/Windows and OS/2 products. 
Each has an optional kit for NFS (Network File System). 

In addition, both DOS/Windows and OS/2 have program- 
mer’s Toolkits that support the most common application 
interfaces. Applications can be written using either the 
DOS or OS/2 products that can communicate with either 
IBM systems such as MVS/CICS or non-IBM systems. 


TCP/IP Support 
O$/2 


FTP (File Transfer) C/S 
TELNET (Terminal Access) 
VT100 C/S 
VT220 G 
4270 LR 
SMTP (Mail) GJS 
LPR/LPD (Print) C/S 
REXEC (Remote Command) C/§ 


NFS Support C/S 


Windows SOCKETS API — 
SOCKETS / 
RPC-SUN Remote Procedure Call ¥ 
FTP API (File Transfer) / 
KERBEROS (Authentication) / 
NCS (Network Computing) v 
C=Chient 
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Ws Advanced 
Services 


mie printing for 
your LAN. 


Bring the power and sophistication of IBM's Advanced 

Function Printing™ technology to your LAN with IBM 

Print Services Facility/2™. Version 1.0 functions as a LAN 

print server, supporting multiple workstations, data streams 

and printer types — a great solution for your high-function, 

high-capacity or departmental printer requirements. For 

your distributed printing needs Version 1.10 is the best 

solution. It consolidates printing throughout the enterprise 

by allowing both the host and workstation application data 

to be printed on a wide range of LAN-attached printers. 

Version 1.0: 

¢ Supports DOS, Windows, OS/2, UNIX and AIX. 

¢ Supports all IBM IPDS Page Printers as well as other 
printer data streams, including HP PCL and PPDS. 

¢ Provides local control of spools, printers and resources. 

¢ Server runs OS/2. 

¢ Includes host and LAN printer sharing solution. 

¢ Supports S/370 and AS/400 via file transfer. 

Additionally, Version 1.10: 

¢ Supports PostScript data stream and Adobe® Type 1 font. 

¢ Works with IBM OS/2 and Novell NetWare® LANS. 


RUMBA/400 
for Microsoft 


Direct to your 
AS/400 files. 


Install RUMBA/400™ on any personal 

computer running Microsoft Windows 

3.0 and you have a graphical interface to access host infor- 

mation directly from a workstation. With RUMBA/400 

you can create direct links that simultaneously update 

your PC files with the same changes you've made in the 

corresponding host application. Available as a feature of 

OS/400 PC support with V2R2 or as a standalone product 

for V2R1 or V2R1.1. 

¢ Provides the tools to define your own text hot spots 
and activate common AS/400 or PC functions. 

e Makes macro customization easy. 

e EHLLAPI and DDE interfaces and Context Sensitive 
Help are available. 

¢ Supports SAA OfficeVision™/400 and 5250 display 
and printer emulation. 


Windows 





Order direct. | 800 IBM-CALL. 
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PSF/2 gives you 


Presentations 
come to life! 


MMPM/2 is the multimedia platform for 
today and tomorrow. It rakes advantage 
of OS/2 2.0 features that make multimedia effective. This 
includes multitasking, which is essential for playing mul- 
tiple data streams concurrently, and for playing synchro- 
nized audio and video. 

MMPM/2 is also the multimedia platform for the future. 
Its extendable architecture enables new functions, devices 
and multimedia data types and formats to be added as the 
technology advances. 
¢ Provides multimedia extensions to the OS/2 32-bit 

environment. 
¢ MMPM Toolkit/2 contains C language bindings, sample 

programs and documentation to assist you in the use of 

MMPM/2. 
¢ Recognizes a variety of audio and image data types. 

e Provides open extendable architecture, data standards 
and consistent user interface. 
« Provides synchronization support by taking advantage 

of the multitasking capabilities in OS/2 2.0. 

*« Provides CD-ROM/XA interleaved data and compressed 
audio support. 


Multimedia 


Presentation 


Manager/2 


Trademarks used in this catalog: IBM, OS/2, OS/400, AS/400, DB2, The Integrated 
Reasoning Shell, APL2 and AIX are registered trademarks of International Business 
Machines Corporation. SAA, SQL/DS, Presentation Manager, RISC System/6000, CICS 
OS/2, BookManager, CUA, MVS, VM, Print Services Facility, Advanced Function Print- 
ing, 8/390, Office Vision and TIRS are trademarks of Internarional Business Machines 
Corporation, UNIX is a registered trademark of UNIX System Laboratories, Inc. 
RUMBA/400, Windows and Word are trademarks and Microsoft is a registered trade- 
mark of Microsoft Corporation. WordPerfect is a registered trademark of WordPerfect 
Corporation. KnowledgeWare is a registered trademark of Knowledge Ware, Inc 
InfoSpan and IRMS are trademarks of InfoSpan Corporation. BACHMAN / Database 
Administrator, BACHMAN/DBA, BACHMAN /Analyst, BACHMAN/Designer and 





iu Put a book in 


BookManager ; 
ims your window. 


Easily find and manage your company’s 
increasing amounts of information with 
the IBM BookManager™ family of products — BUILD and 
READ. With the IBM SAA BookManager BUILD/2, you 
can convert documents created with WordPerfect® and 
MicroSoft Word™ into online-readable, electronic books. 
These books can then be accessed and viewed using either 
the IBM SAA BookManager READ/2 or BookManager 
READ/DOS products. These programs organize books into 
electronic bookshelves allowing you to access information 





immediately through sophisticated search and link capabili- 


ties, within and across books. 

Users’ books and documents can be built and placed on 
the electronic bookshelf right next to softcopy books from 
IBM, and numerous other information providers who 
utilize the BookManager format. 

e Get quick access to softcopy documents stored on a 

LAN server, AS/400 folder, diskette or CD-ROM. 

* Able to use softcopy books in many languages. 

* Displays image data and graphics within softcopy 
publications. 

* Displays more than one book at a time with OS/2 

Presentation Manager multitasking. 

* BookManager READ/DOS 1.2 allows users to find, 


read and use information at their DOS workstations. 


Program No. OTC 
5871-AAA Print Services Faciliry/2 

FIC 2556 PSF/2 V1.0 $2,900 

FIC 2564 PSF/2 V1.1 $2,900 
5738-PC1L PC Support/400 

FIC. 0795 RUMBA/400 Workstation Fearure $365 
5799-PLT RUMBA/400 PRPQ $414 
BookManager Tools 
5601-454 BookManager READ/2 V1.2.1 $203 
5601-453 BookManager READ/DOS 1.2 $203 
587 1-BBB* 

FIC 3779 — BookManager BUILD/2 V1.2.1 $895 
5871-AAA Multimedia Presentation Manager 

FIC 2592 MMPM/2 $125 

F/C2593 MMPM Toolkit/2 $199 


*Limired availability scheduled 12/92. Call for details. 


BACHMAN /Capture are trademarks of Bachman Information Systems, Inc, Micro 
Focus ts a registered trademark and Micro Focus COBOL, Micro Focus CICS Option, 
Micro Focus CICS OS/2 Option, Micro Focus IMS Option and Micro Focus IMS 
Production Option are trademarks of Micro Focus Limited. Novell, NetWare and 
NetView are registered trademarks of Novell, Inc. 1386 and 1486 are trademarks of 
Intel Corporation. HP is a registered trademark of Hewlete-Packard Company. Apple 
is a registered trademark of Apple Computer Corporation. SUN is a registered 
trademark of SUN Microsystems, Inc. Adobe is a registered trademark of Adobe 
Systems Inc. DEC is a registered trademark of Digital Equipment Corporation. 
EASEL Workbench is a registered trademark of Easel Corporation, 


Order Worksheet 


To order, just call: 1 800 IBM-CALL 
Fax to: 1 303 939-2014 

Mail to: 

IBM Corporation 

Catalog Solutions Order Center 

P.O. Box 2150 


Department 518 
Aclanta, GA 30301 


Ship to: 
Name 
Title 
Company 


Address 
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Program Feature Code Media 
Product Number (ifapplicable) (ifapplicable) Price 





Order direct from IBM. 
For the convenience of ordering by phone, call 1 800 IBM-CALL from 
8:00.a.m. to 7:00 p.m. ET, Monday - Friday, 


Send no money now. 

Send no money now. Payment is due at the end of the test period. If 
no test period applies, payment is due upon receipt of invoice. All 
orders are subject to normal IBM credit approval. 


Free shipping! 

We'll process your order immediately and you may expect delivery in 
2-3 weeks. All domestic (continental U.S.) software shipments are 
made at nocharge. 


Licensing information for IBM programs. 

The IBM programs featured in this catalog are offered under the terms 
of either the IBM Customer Agreement (ICA) or the IBM Program 
License Agreement (PLA). Program warranty information is included 
with the program or in the IBM Customer Agreement. Complete 
documentation regarding licensing terms, warranties, Current prices, 
contracts, volume discounts and product descriptions are available by 
phone, fax or mail. 


Cooperative Software Programs 
Cooperative Software Programs GE are provided by IBM Business 
Partners and marketed by IBM acting as anagent. 


Prices in this catalog are subject to change without notice and do not include 
applicable sales rax. The symbol OTC refers to a One Time Charge for che 
product. 
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IBM SAA Personal AS/2 is designed to 
work with IBM’s Systems Application 
Architecture environments. It provides OS/2 users with 

a combination of powerful facilities to gather, analyze and 
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« Enable you to access data in a wide range of personal 
computer data formats, OS/2 Relational, AS/400 and 
System/370 data via Application System 

e Give you comprehensive report and charting capabilities 
to create and customize reports and charts in the style 


you need. : : 

¢ Visually link processes together in a procedure that can Ordering Information 

be run later against the current information. Peueran Pa wy a 
5 5871-BBB Personal Application System 
* Allow you to select data, options and actions right on F/C 0028 —Personal AS/2 Base $763 
the screen with easy-to-use windowing feature. ge Seas ae sly sce 
‘4 ‘ ; i F if @TISTICS 45 

* Optional packages for Statistics, Application Develop- F/C 0060 —_ Business Planning/2 $485 
ment, Business Planning and Project Management FIC 0062 —- Project Management/2 $848 
aia Ae FIC 2530 — Personal AS/DOS for Windows $763 
(OS/2 only) enhance your decision-making capabilities. FIC 2531 Development for Windows $848 
FIC 2532 Statistics for Windows $485 
F/C 2533 Business Planning for Windows $485 
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handle is used for subsequent access to the 
device driver. 


When an application makes a call to a device 
driver, the kernel intercepts the call and 
formats the device driver request into a 
standard request packet, which contains data 
and pointers that the device driver uses to 
complete the request. In the case of a DosRead or 
DosWrite command, the request packet contains 
the verified and locked physical address of the 
caller's buffer. In the case of an I0Ct1, the 
request packet contains the virtual address of a 
data and parameter buffer. Depending on the 
type of request, the data in the request packet 
changes but its header length and format 
remain fixed. The kernel sends the request 
packet to the driver by passing a 16:16 pointer 
to the packet. 


OS/2 device drivers are loaded at boot time. 
The kernel! keeps a linked list of installed 
device drivers by name, using the link pointer 
in the device header. Before a device driver is 


used, it must be DosOpened from the application. 


The DosOpen command specifies an ASCII-Z 
string with the device name as a parameter. 
The device name is an eight-character ASCII 
name located in the device header. The kernel 
compares this name with its list of installed 
device drivers and, if it finds a match, calls the 
OPEN section of the device driver strategy 
routine to open the device. If the device opens 
successfully, the kernel returns to the 
application a handle to use for future device 
driver access. The device handles are usually 
assigned sequentially, starting with 3, as 0, 1, 
and 2 are claimed by OS/2. However, handle 
value should never be assumed. 


DEVICE DRIVER MODES 


OS/2 2.0 device drivers operate in three 
different modes. The first, INIT mode, is a 
special mode entered during system boot and 
executed at Ring 3. When the OS/2 system 
loader encounters a DEVICE= statement in the 
CONFIG.SYS file, it loads the device driver 
SYS file and calls the Init function of the 
device driver. What makes this mode special is 
that the boot procedure is running in Ring 3, 
which normally has no I/O privileges. In this 
mode, however, OS/?2 allows a limited 
number of Ring 0 operations. The device 


driver is free to do port I/O and turn off the 
interrupts, but it must insure that they are on 
before exiting the INIT routine. The INIT routine 
can be used to initialize a universal 
asynchronous receiver transmitter (UART) or 
anything else necessary to ready a device. 





Ring 3 operation during INIT is necessary to 
protect the integrity of code that has already 
been loaded and to make sure that the device 
driver itself does not corrupt the operating 
system during initialization. During INIT, the 
device driver can call a limited number of 
system API routines to aid in the initialization 
process. For example, a device driver might 
use the API routines to read a disk file that 
contains data to initialize an adapter. The 
device driver also uses the API routines to 
display driver error and sign-on messages. 


typedef struct ReqPacket { 
UCHAR RPLength; 
UCHAR RPunit; 
UCHAR RPcommand; 
USHORT RPstatus; 
UCHAR RPreserved[4]; 
UCHAR — RPqLink; 
UCHAR avail[19]; 
} REQPACKET; 


// request packet length 
// unit code for block DD only 
// command code 

// status word 

// reserved bytes 

// queue Linkage 

// command specific data 





Figure 2; OS/2 request packet 


The second mode, called Kernel mode, is in 
effect when the device driver is called by the 
kernel as a result of an I/O request. 


The third mode, called Interrupt mode, is in 
effect when the device driver's interrupt 
handler executes in response to an external 
interrupt such as a character being received 
from a serial port. 


In general, the OS/2 device driver consists of a 
strategy section, an INIT section, and optional 
interrupt and timer sections. The strategy 
section receives requests from the kernel in the 
form of a request packet. The strategy section 
verifies the request, and if it can be completed 
immediately, completes the request and sends 
the result back to the kernel. If the request 
cannot be completed immediately, the device 
driver optionally queues the request to be 
completed at a later time and, if necessary, 
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starts the [/O operation. The kernel calls the 
strategy routine directly by finding its offset 
address in the device header. 


REQUEST PACKETS 


The first entry in the request packet is the 
request packet length, filled in by the kernel. 
The second parameter is the unit code. 


typedef struct DeviceHdr { 
struct DeviceHdr far *DHnext; /* ptr to next header 


USHORT DHattribute; 
OFF  DHstrategy; 


OFF  DHidc; 


UCHAR DHname[8]; 


/* device attribute word 

/* offset of strategy routine 
/* offset of IDC routine 

/* dev name (char) or #units 


char _reserved(8]; 


} DEVICEHDR; 


DEVICEHDR devhdr = { 


(void far +) OxFFFFFFFF, 
(DAW_CHR | DAW_OPN | DAW_LEVEL1), 
(OFF) STRAT, 


(OFF) 0, 


“DEVICE1 “, 


es 


/* Link +/ 
/* attribute */ 
/* &strategy +*/ 
/* &TDCroutine */ 
/* device name */ 





Figure 3; OS/2 device driver header 


DEVICEHDR devhdr[2] = { 


{ (void far *) &devhdr[1], 


/* Link to next dev+*/ 


(DAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute +/ 
(OFF) STRAT1, 
(OFF) 0, 

"DEVICE “, 
}, 


{(void far *) OxFFFFFFFF, 


/* &strategy +/ 
/* &1DCroutine +/ 


/*1ink(no more devs)*/ 


 (OAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute */ 


i* 


(OFF) STRAT2, 
wii He ) 0, 


/* &strategy */ 
/* &1DCroutine + 





Figure 4: Device driver header, multiple devices 


Applicable for block devices only, this field 
should be set by the device driver writer to 
zero for the first unit, one for the second, and 
so on. The third field, the command code, is 
filled in by the kernel. This is the code used by 
the switch statement in the strategy section to 
decode the type of request from the kernel. The 
next field is the status word returned to the 


kernel. This field will contain the result of the 
device driver operation, along with the DONE bit, 
to notify the kernel that the request is complete. 
(This is not always the case; the device driver 
may return without the DONE bit set.) To make 
things easier, a C language union should be 
used to access specific types of requests. The 
request packet structures are placed in an 
include file, which is included by the device 
driver mainline. 


THE DEVICE HEADER 


A simple OS/2 device driver consists of at least 
one code segment and at least one data segment, 
although more memory can be allocated if 
necessary, as in Figure 2. The first set of data 
that appears in the data segment must be the 
device driver header, a fixed-length linked list 
structure that contains information for use by 
the kernel during INIT and normal operation, as 
in Figure 3. 


The first entry in the header is a link pointer to 
the next device the device driver supports. If no 
other devices are supported, the pointer is set to 
- iL. A- iL terminates the list of devices 
supported by the driver. If the driver supports 
multiple devices, such as a four-port serial 
board or multiple disk controller, the link is a far 
pointer to the next device header, as shown in 
Figure 4. When OS/2 loads device drivers at 
INIT time, it forms a linked list of all driver 
device headers. The last device driver header 
will have a link address of - 1L. When a DEVICE= 
statement is found in CONFIG.SYS, the last 
loaded device driver’s link pointer is set to point 
to the new driver’s device header, and the new 
driver's link pointer now terminates the list. 


The second entry in the device header is the 
device attribute word, which is used to define the 
operational characteristics of the device driver. 


The third device header entry is a one word 
offset to the device driver strategy routine. Only 
the offset is necessary because the device driver 
is written in the small model with a 64K code 
segment and a 64K data segment. (This is not 
always true; in special cases, the device driver 
can allocate more code and data space if needed, 
and can even be written in the large model.) 


The next entry in the device header is an offset 
address to an IDC routine, if the device driver 
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The Arcadia Workplace Companion (WP(C) Is a set 
of productivity tools designed specifically for the 
OS/2 Workplace Shell environment from the ground 
up! It adheres to Common User Access (CUA) '91 
guidelines and completely integrates its various 
components in an object-oriented fashion. The WPC 
exploits all of the powerful new 
controls found within OS/2 2.0 
including notebooks, containers, 
sliders, value sets, and spin buttons. 


Everything necessary to schedule 
the days events, keep track of 
appointments, and manage 
business contacts is represented 
graphically. The Workplace 
Companion contains a clock/calendar module, an 
appointment book, a telephone/address book (with 
phone log), a notepad, a to-do list, and other 
productivity features. 


— 


Arcadia 
Technologies 


_M 
” 4 Inc. 


OS/2, CUA, IBM are registered trademarks of International Business 
Machines, Corporation. Arcadia Workplace Companion is a trademark of 
Arcadia Technologies, Incorporated. 
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Clock/Calendar. This module contains a month 
calendar, a full-year calendar, Julian date, 
analog/digital clock, international times, holidays, 
and more! It allows you to customize Its many 
features, such as setting your own alarms and 
adding new cities to the international cities list. 


Appointment Book. The 
Appointment Book is an excellent 
way to schedule your day's events. 
Appointments may be added by 
clicking on the time you wish to 
schedule and typing a description. 


Telephone/Address Book. This 
module is a convenient way to store 
the name, numbers, and addresses of all your 
important contacts. The built-in Phone Log and 
Follow-up feature make tracking phone calls easy. 





735 West Duarte Road, Suite 20 
Arcadia, CA 91007 


(818) 446-6945 
Fax: (818) 447-4212 
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supports interdevice driver communications. 
(The DAW_IDC bit in the device attribute word 
must also be set or the AttachDD call from the 
other device driver will fail.) The last field is the 
device name, which must be eight characters in 


Device Attribute Word 


The device attribute word describes the type of 
driver and its capabilities. OS/2 uses this 
information for calling the device driver. 


Device attribute word bits are described in 


length. Names with less than eight characters 
| Table 1. 


must be blank filled. Any mistake in coding the 
device driver header will cause an immediate 


crash and burn when booting. Capabilities Bit Strip 


The capabilities bit strip word defines 
additional features supported on level 3 


DEVICE ATTRIBUTE WORD drivers only, as shown in Table 2. 
Bits Description 

| THE STRATEGY SECTION 
15 Set if character driver, 0 if block driver 

a oe . Pore The strategy section is nothing more than a big 
14 Set if driver supports interdevice communications (IDC) *% 3 ore: 

switch statement, as shown in Figure 5. 

13 For block drivers, set if non-IBM format; for character drivers, Common device driver requests, such as 


DosWrite and DosRead, have predefined function 
codes assigned to them. The device driver may 
elect to ignore any or all of these requests by 
returning a DONE status to the kernel, noting 
that the request has been completed. The 
status returned to the kernel may include error 
information, which the kernel returns to the 
calling program. 


set if driver supports output-until-busy 
12 If set, device supports sharing 


11 Set, if block device supports removable media; if character 
device supports device open and close 


10 Reserved, must be 0 


9-7 Driver function level;001 = OS/2 device driver 
010 = supports DosDev10Ct12 


011 = capabilities bit strip in device header In the case of one of the standard device driver 


functions, the kernel maps the error value 
| 64 Reserved, must be 0 returned from the device driver to one of the 
standard device driver return codes. It is 


3 Set if this is the CLOCK device therefore impossible to pass any special return 
7 Set if this is a null device (character driver only) codes to the application by way of a standard 
device driver request. 
1 Set if this is the new stdout device 
If the device driver must return special error 
0 Set if this is the new stdin device codes, it must use an I0Ct1 request. I0Ctls are 


used for special types of device driver-specific 
operations such as port I/O that don’t fit into 
the architecture of the standard device driver 
functions. The I0Ct1 section of the device 
driver is called when the application issues a 
DosDevI0Ctl call with the device driver's handle. 
Using I0Ctls, the device driver can return 
specialized codes that might contain, for 
example, the contents of an I/O port or the 
status of the device. This flexibility allows the 
driver writer to customize the device driver to 
fit any device. 


Table 1: Device attribute word 


CAPABILITIES BIT STRIP 
Bits Description 


0 Set if driver supports DosDev10Ct12 packets and has 
shutdown support 


For character drivers, set if driver supports 32-bit 
memory addressing; for block drivers this bit must be 0 


If set, the device driver supports parallel ports 


The strategy section is entered when the kernel 
calls the device driver to perform a particular 
operation. 


Reserved, must be 0 





Table 2: Capabilities bit strip 
20 
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AM(Applications Manager)...the only 0$/2 client/server development tool provid- 
Ing 32-bit applications exploiting the Workplace Shell and accessing data from local LAN 
or remote host databases. AM increases productivity at least 10-fold compared to 
conventional application development languages. AM is currently in use by over 1,000 
organizations worldwide and is the leader in the delivery of proven, live applications. 
You too can experience the power... CALL NOW...508+640+ 1080. 
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INITIALIZATION 


The INIT call is made only once during system 
loading in response to a DEVICE= in the 
CONFIG.SYS file. The call is made in the INIT 
mode from Ring 3, but with I/O privileges. 
The INIT routine is generally used at a time 
when code is inserted to initialize a device, 
such as setting up a serial port or verifying that 
the correct hardware is installed. 


int main(PREQPACKET rp, int dev) 
{ 


switch(rp->RPcommand) 
case RPINIT: /* 0x00 */ 


/* init called by kernel in protected mode +*/ 

return Init(rp); 
case RPREAD: 

return (RPDONE); 


/* 0x04 */ 


case RPWRITE: /* 0x08 */ 


return (RPDONE); 
case RPINPUT_FLUSH: /* Ox07 #/ 

return (RPDONE); 
case RPOUTPUT_FLUSH: /* Ox0b +/ 
return (RPDONE); 


case RPOPEN: 
return (RPDONE); 


/* Ox0d */ 


case RPCLOSE: /* Ox0e */ 


return (RPDONE); 


case RPIOCTL: /* 0x10 */ 
switch (rp->s.I0Ctl. function) 
{ 


case 0x00: /* our function def #1 */ 
return (RPDONE); 


case 0x01: /* our function def #2 */ 
return (RPDONE); 


/* deinstall request */ 
case RPDEINSTALL: /* 0x14 */ 
return(RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


/* all other commands are flagged */ 
default: 

return(RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
} | 





Figure 5; Skeleton strategy section 








The first thing the driver should do during 
initialization is to save the DevH1p entry point 
address passed in the request packet. This is 
the only time that the address is made 
available to the device driver, and it must be 
saved in the device driver's data segment. 


The INIT code generally performs two other 
functions. First, it issues a sign-on message to 
the screen that the device driver is attempting 
to load. Second, it finds the address of the last 
data and code item and sends them back to 
OS/2. OS/2 uses the code and data offset 
values to size memory. Only the first code and 
data segment of the device driver are resized 
by OS/2, so it may be desirable to place the 
INIT code and data into another segment, 
which is discarded after the device driver is 
loaded, If a device driver fails installation, it 
must send back zero offsets for its code and 
data segments so OS/2 can use the memory 
space the device driver occupied during 
installation, 


If the driver supports multiple devices, it will 
contain a device header with an entry for each 
device, with one device header pointing to the 
next, as shown in Figure 6, The last device 
header contains a -1L, which terminates the 
list. For each device, the OS/2 kernel calls the 
strategy entry point to initialize the device. If 
the driver supports, for example, four serial 
ports that use a single interrupt level, only the 
last valid initialized device should hook the 
interrupt. This prevents previously installed 
devices from generating interrupts before 
initialization is completed. The code and data 
segment values returned to OS/2 to size 
memory should be exactly the same each time 
the Init section is called. 


During INIT, a limited number of API functions 
can be called by the device driver. This is 
possible because INIT runs as a Ring 3 thread. 
These calls are especially helpful for 
initializing device drivers using data that is 
resident in files. 


The driver should allocate necessary resources 
such as memory and GDT selectors during 
initialization. If the driver supports a memory 
mapped adapter, the physical adapter address 
can be mapped to a GDT selector. However, 
because INIT is performed as a Ring 3 thread, 
the GDT selector cannot be accessed during 
initialization. 
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If the driver is installed on an IBM PS/2™ Micro 
Channel™ machine, the device driver should 
search the system for an adapter card with the 
correct ID and verify that it is configured 
correctly. The device driver may also call special 
PS/2 Advanced BIOS (ABIOS) routines to verify 
the correct configuration. 


A COMMON STRATEGY 


One of the most common techniques in OS/2 
device driver design is for the strategy section to 
request service from the device and wait fora 
device or timer interrupt to signal completion of 
the request. In this case, the strategy section 
starts the I/O and issues a Block DevHlp call, 
which blocks the calling thread. When the device 
interrupt signals that the operation is done, the 
interrupt section runs the blocked thread, 
completing the request. To protect against the 
request never being completed, as with a down 
device, the Block call can contain a time-out 
parameter. If time expires before the completion 
interrupt occurs, the Blocked thread will be run, 
allowing the strategy section to send the proper 
error message back to the kernel. 


Another way to time-out a device is to use the 
SetTimer DevHlp routine. A timer handler can be 
hooked into the OS/2 system clock, and ticks 
counted until the timer handler decides to run 
the Blocked thread. 


The number and type of commands supported 
by the strategy section are up to the designer of 
the device driver. The device driver can process 
only the commands it needs to, and let the others 
pass through, by sending a DONE status back to 
the kernel. Illegal function calls may, optionally, 
be trapped, and an ERROR_BAD_COMMAND returned to 
the kernel. 


The OS/2 kernel periodically issues special 
requests to the device driver, such as the 5-48 
Code Page JOCTL, which the kernel sends to 
every OS/2 device driver immediately 
following the Open:. 


If the application has a pending request blocked 
in the device driver when it failed, the kernel 
unblocks the device driver with an “unusual 
wakeup” return code. The device driver must 
then return ERROR_CHAR_CALL_INTERRUPTED to the 
kernel, which, in turn, calls the CLOSE section of 
the driver. 


In general, it’s a good practice to trap all 
unsupported requests by returning the DONE and 
ERROR_BAD_COMMAND status to the kernel. 





In the simplest of device drivers, the strategy 
section may contain only Open, Close, and Read or 
Write. Ina complicated driver such as a disk 
device driver, the strategy section may contain 
over two dozen standard device driver functions 
and dozens of additional I0Ct1 calls. I0Ct1 calls 
are actually strategy functions, but are broken 
down one step further to provide more detailed 


DEVICEHDR devhdr [2] = { 
{ (void far *) &devhdr [1], 
(DAW_CHR | DAW_OPN | DAW_LEVEL1), 
(OFF) STRAT1, 
(OFF) 0, 
“DEVICE1 “, 
}, 


((void far *) OxFFFFFFFF, 
(DAW_CHR | OAW_OPN | DAW_LEVEL1), 
(OFF) STRAT2, 

(OFF) 0, 

“DEVICE2 “, 

}, 


//Link to next dev 
//attribute 
//&strategy 
//®TDCroutine 


//Link(no more devs) 
//attribute 
//astrategy 
//#IDCroutine 








Figure 6: Device driver header, multiple devices 


or device-specific operations. For instance, an 
application might send a list of parameters to a 
device driver to be used in initializing an I/O 
port. This operation would not be possible using 
one of the standard device driver function calls 
because it is so device-specific. The I0Ct1, 
however, is well suited to this type of function. 


INTERRUPT SECTION 


The interrupt section handles interrupts from the 
device. Interrupts may be caused by a character 
having been received, a character that has 
finished transmitting, or any number of external 
events. Interrupt processing should be quick and 
straightforward. The routine that handles the 
interrupt is appropriately called the interrupt 
handler, a subroutine entered at every interrupt 
for the IRQ level registered with the SetIRQ DevHlp 
call. All interrupts in OS/2 are handled by the 
kernel, a change from DOS, where a program 
had only to hook the interrupt vector it wanted. 
OS/2 does not allow interrupt vectors to be 
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changed, and if an attempt is made to change 
one, the application is immediately kicked off 
the system. To register for an OS/ 2 interrupt, 

the device driver must send the address of its 
interrupt handler and the requested interrupt 


(IRQ) level to OS/2 through a SetIRQ DevHlp call. If 


the SetIRQ is successful, OS/2 calls the interrupt 
handler upon receipt of an interrupt on that IRQ. 


OS/2 calls each registered interrupt handler 
until one claims ownership of the interrupt by 
clearing the carry flag (CLC). The interrupt 
handler must be in the first code segment of the 
device driver. 


OS/2 calls the device driver's interrupt handler 
with interrupts disabled if the device driver 
registered for the interrupt as nonshared (ISA 
bus). If the SetIRQ call is made with the shared 
interrupt option (Micro Channel, EISA), 
interrupts remain enabled when the interrupt 
handler is entered. Shared interrupts are a 
feature of the IBM Micro Channel and EISA bus 
architectures, which allow more than one device 
to share a single interrupt level. 


Extended time in the interrupt handler can 
cause performance problems. Since the interrupt 
routine is frequently entered as a result of data 
being received, the interrupt handler must 
quickly store the data and exit. In the case of 
character devices, the OS/2 Devilp library 
supports fast reads and writes to circular 
character queues. For block devices, interrupt 
handling is fast because the interrupt is usually 
caused by a DMA completion or disk-seek 
complete, For block devices, data is usually 
transferred to the user buffer using DMA, 
eliminating the need to transfer data during 
interrupt processing, On a DMA transfer, the DMA 
controller is set up and started, and the device 
driver exited to allow other threads to run. 
When the DMA completes, it generates a DMA 
completion interrupt, causing the device driver 
interrupt handler to be entered, The interrupt 
handler then takes the appropriate action, for 
example, starting a new DMA transfer. 


Most UARTs and adapters have some type of 
buffering, which allows a device driver some 
slack in servicing higher data rates. When an 
interrupt occurs, the UART is examined to 
determine the type of interrupt: transmit, 
receive, or clock. 


The interrupt handler is not entered directly 
from OS/2, but is called from a small assembly 





driver startup language routine. When the 

Set IRQ call is made to register the interrupt 
handler, the address passed in the call is the 
address of the interrupt handler entry point in 
the device driver start-up code. The start-up 
code, in turn, calls the C interrupt handler. 


The interrupt handler routine is not difficult to 
write or understand. It can, however, be difficult 
to debug, Errors that occur in the interrupt 
handler frequently appear only in a real-time 
context, that is, while the interrupt handler is 
being entered because of a hardware interrupt. 
The C library function printf, for example, 
cannot be called from within an interrupt 
handler. Application debuggers such as 
CodeView™ cannot be used in an interrupt 
handler; rather, a debugger such as the OS/2 
KDB must be used. A breakpoint placed in the 
interrupt routine will cause the program to stop, 
and further interrupts may pass undetected 
while the program is stopped. A problem may 
not appear when breakpoints are inserted, but 
will reappear when the program executes 
normally. It then becomes necessary to visualize 
the operation of the interrupt handler and begin 
applying solutions until the problem is fixed. 


The interrupt handler may receive unsolicited 
or spurious interrupts from the hardware, 
which should be handled. In the sample 
interrupt handler, a check is made to see 
whether a valid read or write request is 
pending. If not, the device is reset and the 
interrupt handler is exited, effectively ignoring 
the interrupt. 
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LAN Interoperability 


with OS /2 2.0 


by Bob Spratt 


In the past few months, a new buzzword has 
appeared in the area of computer networking. 
“Interoperability” is suddenly getting attention in 
the local area network (LAN) world. 


Interoperability is commonly known as the ability 
to communicate with multiple communication 
protocols from a single system at a single instance 
in time. This definition can also be expanded to 
include the ability of a workstation to use the 
multiple protocols on a single network adapter 
without conflict. A single workstation can access 
different types of server resources on the same 
network at the same time with one or more network 
adapters. For example, an OS/2 workstation can 
share files simultaneously on a NetWare™ server, 
an OS/2 LAN server, a Vines™ server, and a 
TCP/IP NFS server on a single LAN. 


This article describes interoperability and explains 
why it is necessary in today’s LAN environment. It 
also shows how OS/2 2.0 pravides the mechanisms 
necessary for easy interoperability and explains 
how to get an interoperable system working with 
progranis available from IBM and other suppliers. 


At the time this article was written, neither the 
NetWare nor the Vines requester was finalized, so 
there may be some minor discrepancies between this 
article and the actual final product, most likely in 
the section that describes how to install individual 
pieces. This article can still serve as a guide for 
creating an OS/2 requester that can communicate 
with multiple servers. 


This article describes how to make interoperability 
work using token-ring (T/R) as an example. T/R is 
used for illustration purposes; it can be replaced 
with another supported network medium such as 
Ethernet. 


INTEROPERABILITY 


[ evceres may wonder about the 
practical applications of interoperability. 


Today’s LAN environments use many 
different communication protocols, ranging 
from NetBios and IEEE 802.2 in the OS/2 LAN 
Server environment to IPX and SPX in the 
NetWare environment. There are many other 
protocols, including Vines IP from Banyan and 
TCP/IP. In most large corporate networks and 
many smaller networks, these protocols are 
being used to communicate between different 
types of machines. Interoperability gives users 
the ability to access resources on any machine 
on the network, regardless of the protocol 
being spoken. 


The network in Figure 1, for example, consists 
of three PS/2 Model 95s running NetWare 


Token Ring, Ethernet, Etc. 





OS/2 2.0 Requester 





Figure 1; Network example 
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Figure 2: The NDIS protocol stack with ODI support 


from IBM, OS/2 LAN Server, and Banyan 
Vines. Other types of computers are also 
present on the LAN: an RS/6000, an AS/400, 
and an ES/9000. Each of these machines 
provides some resource to the user at a 
workstation. With interoperability, a user can 
access resources On any machine. 


OS/2 provides the perfect base operating 
system for this situation, one with connective 
capabilities that allow multiple 
communications protocols to be spoken over a 
single network adapter. This eliminates the 
need for multiple adapters to support multiple 
protocols, as was the case with early operating 
systems. 


Interoperability is not limited to LANs, but can 
be extended to include other communications 
protocols. OS/2 Extended Services (ES) 
includes Communications Manager, a product 
that can communicate with host systems such 
as the ES/9000. System links using ES and LS 


OS/2 2.0 Network Applications 


are maintained when used in conjunction with 
other protocols such as Vines and NetWare. 


All these protocols have implementations 
specifically designed for OS/2 2.0, and all 
except NetWare are based on the Network 
Driver Interface Specification, or NDIS. 
(NetWare is based on the ODI specification; as 
a special case, it will be discussed later.) 


WHAT IS NDIS? 


NDIS, jointly developed by Microsoft and 
3Com, provides a network driver architecture 
and interface that allows a system to support 
multiple network adapters and protocols. It 
provides a mechanism for managing these 
protocols and adapters so that different 
protocols can be used on different cards. 


As a working definition, NDIS is a mechanism 
to support one or more network protocols on 
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Figure 3: The ODI protocol stack with NDIS support 


one or more network adapters. The adapters MAC-Layer Entities 

may or may not be of the same type. For 

instance, Ethernet and T/R adapters can be MAC-layer entities bring the MAC-layer 

used in the same system. interface up to a user level for tools and test 
purposes. Further discussion of these entities is 

NDIS defines four types of drivers used to beyond the scope of this article. 


support communications. 
Protocol-Manager Driver 
Media Access Control (MAC) Driver 
The protocol-manager driver provides a 


MAC drivers are traditional device drivers for standard way for MAC and protocol drivers to 

the network adapter. They provide low-level receive configuration information about 

access to the hardware. MAC drivers’ primary themselves and each other. It allows multiple 

responsibility is to provide basic packet drivers to bind together to create a desired 

transmission and reception functions. protocol structure. Information used by the 
protocol manager is stored in the file PROTOCOL . INT. 

Protocol Driver 

Protocol drivers provide a higher level of WHAT IS ODI? 

support ranging from the data link to the 

application layers of the OSI model. Protocol Novell defines ODI as open data-link interface. 

drivers include NetBios and IEEE 802.2. ODI supports media and protocol- 


independent communications with a standard 
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‘To a software 
developer, this is what 
heaven looks like. 


Most people wouldn't know what to make of a screen like 
this. But developers like you know a screen like this can 
help make all kinds of applications. With OS/2* 2.0, you 
can develop the DOS, Windows,’ OS/2 and host-ba sed 
apps end users need. And you can do it faster and easier 
than ever before. Because OS/2 2.0 can make the most 
of your 386 or 486 processor. 

Now you can edit in one window, compile in 
another, profile in a third and test in a fourth. Pre- 
emptive multitasking makes everything run smoothly 
and responsively. And OS/2 Crash Protection” helps 
shield running applications from each other, so if one 
goes down it won't affect the others. Instead of reboot- 
ing, you just restart the affected app and continue. 

And since OS/2 2.0 is a 32-bit operating system, pro- 
grams are easier to write and run faster, too. Which all 
adds up to improved productivity and reduced develop- 
ment cycle time. 

But maybe the best part is that for less than the cost 
of DOS and Windows, OS/2 gives you a whole lot more. 
And to keep your cycle rolling, a full range of services 
and support are available, like on-line help through 
OS/2 Support line, Bulletin Board and IBM Link. Or 
you can join the IBMOS2 and OS2DEV 
conferences on CompuServe; where you ay 
can meet IBMers, users and developers ell | 
who can find fast answers to your N 
questions. kor an [BM authorized dealer ~~ 
near you, or to order OS/2 2.0 from 


IBM, call 1 800 3IBM-OS2: 






- OS/2 Crash Protection helps shield applications from each other 
- The integrating platform of choice for DOS, Windows and OS/2. 
+ Preemptive multitasking for responsive, reliable execution. 

+ 32-bit flat address space for productive programming. 

- A full range of IBM services and support, ? 
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XVT's Portability Toolkit” is a powerful 
C development environment that allows you to 
build a single application, then re-compile to every 
major GUI without rewriting code. XVT solutions 
also include an interactive design tool and a class 
library for C++ developers. 
¢ Supports Macintosh, Microsoft Windows, 
Windows NT, OS/2 Presentation Manager, 
OPEN LOOK, OSF/Motif, and Character Systems 
¢ Native look-and-teel to all target GUIs 
¢ Portability to 26 hardware systems 
¢ Access to the complete functionality of every 
windowing system 
Easier to use than native development toolkits 
¢ Minimal size and performance overhead 
e Shorter development cycles 
¢No royalties or runtime fees 
¢ Clear documentation and 
responsive technical support 
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Now in its third generation, XVT is recognized 
as the industry leader in portable GUI 
development solutions and is the base document 
for the emerging IEEE standard. It is used by 
world-class soltware developers like Novell 
eHP eAT&T #Digital eLockheed * Kodak 
© Grammatik/Reference Software, because it allows 
them to take their applications to the widest 
market, quickly and cost ellectively 

Don't write another line of code without gearing 
up to develop your application simultaneously for 
all GUIs. Call for technical materials and a demo. 
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DEVICE=C: \IBMCOM\LANMSGDD.0S2 /1:C:\IBMCOM 
DEVICE=C:\ibmcom\protman.os2 /I:C:\ibmcom 
DEVICE=C: \ibmcom\protocol\LANDD.0S2 
DEVICE=C: \ibmcom\protocol\LANDLLDD.0S2 


LIBPATH=C: \MUGLIB\DLL ;C:\IBMLAN\NETLIB; C: \NETWARE;C:\VINES\DLL;C:\TCPIP\DLL ;C:\ibmcom\d11; 
SET PATH=C: \IBMLAN\NETPROG; C: \MUGLIB;L:\0S2;P:\0S2;C:\NETWARE;Z:\;C:\TCPIP\BIN; 
SET DPATH=C:\IBMLAN\NETPROG; C: \IBMLAN; C: \MUGLIB\DLL;C: \NETWARE;z:\;C:\ibmcom; 


SET HELP=C:\TCPIP\HELP; 
DEVICE=C; \IBMCOM\PROTOCOL\LANPDD.0S2 
DEVICE=C: \IBMCOM\PROTOCOL\LANVDD.0S2 


SET BOOKSHELF=C: \IBMLAN\BOOK; 


REM Comment out the following line if the Novell solution to interoperability 


REM is being used 
DEVICE=C: \IBMCOM\MACS\IBMTOK .0S2 


REM -- NETWARE REQUESTER STATEMENTS BEGIN -- 


DEVICE=C: \NETWARE\LSL.SYS 
RUN=C: \NETWARE\DDAEMON .EXE 


REM Comment out the following line if the Novell solution to interoperability 


REM is being used 
device=C: \ibmcom\protocol\odi2ndi.os2 


Figure 4: Example CONFIG.SYS (continued on page 32) 


interface that allows transport protocols to 

share a single network board without conflict. 
The Novell equivalent to NDIS, ODI supports 
constructs similar to those in the NDIS model. 


Multiple Link Interface Drivers (MLIDS)— 
MLIDs correspond to the NDIS MAC driver, 
providing the same type of functions. 


Protocol Stack—The protocol stack corresponds 
to the NDIS Protocol Driver. Examples include 
IPX/SPX and AppleTalk. 


Link Support Layer (LSL)—The LSL roughly 
corresponds to the NDIS Protocol Manager. It 
is responsible for routing protocols to different 
adapters. 


The most difficult aspect of interoperability 
with OS/2 2.0 is having ODI protocols and 
NDIS protocols exist concurrently. Both Novell 
and IBM have offered solutions. Figures 4 and 
5 give IBM's solution, with changes needed for 
Novell’s solution noted in the code. 





IBM’s solution uses its recently announced 
Network Adapter and Protocol Support 
(NAPS). Its code contains an additional 
protocol driver, ODI2NDI, that provides an 
interface between ODI layers and NDIS, 
allowing ODI-based protocols to communicate 
over the NDIS layer. Because all other OS/2 
protocols are NDIS-based, this is the simplest 
solution. Figure 2 shows a diagram of protocol 
stacks supported by NDIS. 


Novell’s solution is similar to that of IBM, but 
puts an interface between NDIOS and ODI, 
allowing NDIS protocols to communicate over 
the ODI interface layer. Novell adds an 
additional protocol driver called ODINSUP, 
which adds layers to all protocol stacks in the 
system except NetWare. Figure 3 shows how 
ODINSUP connects the NDIS protocols to 
ODI; comparing it to Figure 2 shows the 
differences between the two approaches and 
illustrates path length differences between the 
upper layer applications and the bottom layer 
adapter device drivers. 
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REM Add the following line if the Novell solution to interoperability 
REM is being used 
REM DEVICE=C: \NETWARE\TOKEN . SYS 





DEVICE=C: \NETWARE\ROUTE.SYS 
DEVICE=C:\NETWARE\IPX .SYS 

DEVICE=C: \NETWARE\SPX.SYS 

RUN=C: \NETWARE\SPDAEMON . EXE 

REM DEVICE=C:\NETWARE\NMPIPE.SYS 

REM DEVICE=C: \NETWARE\NPSERVER.SYS 

REM RUN=C:\NETWARE\NPDAEMON.EXE NP_COMPUTERNAME 
DEVICE=C: \NETWARE\NWREQ.SYS 

IFS=C: \NETWARE\NWIFS. IFS 

RUN=C: \NETWARE\NWDAEMON. EXE 


REM Do not use the NetBIOS support that comes with NetWare 
REM DEVICE=C:\NETWARE\NETBIOS .SYS 
REM RUN=C:\NETWARE\NBDAEMON .EXE 


DEVICE=C: \NETWARE\VIPX .SYS 
REM DEVICE=C: \NETWARE\VSHELL. SYS 
REM -- NETWARE REQUESTER STATEMENTS END -- 


DEVICE=C: \IBMCOM\PROTOCOL\NETBEUI.0S2 
DEVICE=C: \IBMLAN\NETPROG\RDRHELP . 200 
IFS=C:\IBMLAN\NETPROG\NETWKSTA.200 /I:C:\IBMLAN /N 
DEVICE=C: \IBMCOM\PROTOCOL\NETBIOS.0S2 


REM >THE NEXT FEW LINES LOAD VINES NETWORK SOFTWARE IN 

REM >REQUIRED ORDER, SET AT INSTALLATION TIME. DONT EDIT 
REM >OR MOVE ANY LINE WITHOUT SPECIFIC VINES INSTRUCTION. 
REM >ALSO, DON’T REMOVE “Z:\” FROM YOUR SET PATH=LINE 

REM >OR “C:\vines-directory\DLL” FROM YOUR LIBPATH=LINE. 
SET VINESDIR=C:\VINES 

IFS=C:\VINES\VINES2.IFS 

DEVICE=C:\VINES\BANCOMM2.SYS /SOCKETS=60 /SPP_CONNECTIONS=60 /KBYTES_COMMBUFFERS=96 
DEVICE=C: \VINES\VBAN. SYS 
DEVICE=C:\VINES\drivers\bn_NDIS\NDISBAN2.SYS 

REM >END OF VINES SOFTWARE INFORMATION. 


RUN=C: \IBMLAN\NETPROG\LSDAEMON . EXE 


SET ETC=C:\TCPIP\ETC 

SET TMP=C:\TCPIP\TMP 

RUN=C: \TCPIP\BIN\CNTRL.EXE 
IFS=C:\TCPIP\BIN\NFS200. IFS 
DEVICE=C:\TCPIP\BIN\INET.SYS 
DEVICE=C:\TCPIP\BIN\IFNDIS.SYS 


RUN=C: \ibmcom\protocol\land11. exe 


RUN=C: \ibmcom\protocol\netbind.exe 
RUN=C: \ibmcom\lanmsgex . exe 


32 Figure 4: Example CONFIG.SYS (continued from page 31) 





MAKING IT WORK 


Most of the work involved in getting all these 
protocols running at the same time has already 
been done by the providers of the protocols. 
The installation packages do a good job of 
configuring the system so all protocols load 
properly and can reside harmoniously in the 
same workstation. Special tailoring is still 
necessary, however, for some components. 


Each of the following sections describes the 
steps necessary to install a piece of the 
network communication protocol support. It is 
recommended that you install them in this 
order. If a particular protocol is not needed, 
skip its section. Although this installation 
sequence is not required, it makes system 
configuration much easier. 


NetWare 
NetWare installation is completed differently 


depending on which interoperability solution is 
chosen, Novell's or IBM's. If you choose the IBM 


rc 
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solution, install NetWare according to the 
instructions provided with the NetWare 
requester. Then install IBM‘’s LAN requester 
and protocol support (LAPS). Be sure to select 
the NetWare protocol, NetBIOS, and 802.2. This 
adds changes to CONFIG.SYS and 
PROTOCOL.INI that configure and run 
ODINDI. Figure 4 gives an example of 
modifying CONFIG.SYS for NetWare support 
with LAPS. Figure 5 shows the section added to 
PROTOCOL.INI for the ODI2NDI device driver. 


If you choose the Novell solution, the following 
steps will ensure LAN interoperability: 


* Install the NetWare requester for OS/2 2.0 as 
per its instructions. COEXIST.TXT, a text file 
on the NetWare requester installation disk, 
can be printed and used to augment the 
information in this article. 


e Be sure to create a NET.CFG file as indicated 
in the COEXIST.TXT document. The 
NET.CFG for a system using T/R is given at 
the end of this article. 
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; Note the “Bindings” lines in each of the 
: protocol sections. In each case, the 
; commented line is to be used instead of the 
: uncommented line when using Novell’s 
: solution to Interoperability. 
[PROT_MAN] 


DRIVERNAME = PROTMANS 
[IBMLXCFG] 


IBMTOK_nif = IBMTOK.nif 
LANDD_nif = LANDD.NIF 
NETBEUL_nif = NETBEUL.NIF 
ODT2NDI_nif = ODI2NDI.NIF 


[LANDD_nif] 


DriverName = LANDD$ 
Bindings = IBMTOK_nif 
Bindings = TOKEN 
ETHERAND_TYPE = “I” 
SYSTEM_KEY = 0x0 
OPEN_OPTIONS = 0x2000 
TRACE = 0x0 
LINKS = 8 
MAX_SAPS = 3 
MAX_G_SAPS = 0 
USERS = 3 
TI_TICK_G1 = 255 
Ti_TICK_Gi = 15 
T2_TICK_G1 = 3 
TI_TICK_G2 = 255 
TI_TICK_G2 = 25 
T2_TICK_G2 = 10 
IPACKETS = 250 
VIPACKETS = 100 
MAXTRANSMITS = 6 
MINTRANSMITS = 2 
TCBS = 64 
GDTS = 30 
ELEMENTS = 800 


[NETBEUI_nif] 


DriverName = netbeui$ 
Bindings = IBMTOK_nif 
Bindings = TOKEN 
ETHERAND_TYPE = “I” 
USEADDRREV = “YES” 
OS2TRACEMASK = 0x0 
SESSIONS = 100 
NCBS = 95 
NAMES = 100 
SELECTORS = 5 
USEMAXDATAGRAM = “NO” 
ADAPTRATE = 1000 
WINDOWERRORS = 0 
MAXDATARCV = 4168 





Figure 5: Example PROTOCOL.INI (continued on page 36) 





¢ When configuring your system to be used 
with NetWare and any NDIS based protocol, 
create NET.CFG, containing the lines in the 
sample NET.CFG, in the root of your boot 
drive. Modify CONFIG.SYS and make the 
following changes: 


a. Remove the line invoking the T/R driver 
installed as part of the NDIS support, most 
likely named IBMTOK.OS2. 


b. Add a line invoking the ODI NDIS 
interface driver (ODINSUP.SYS). See Figure 
4 for details. 


c. Remove the line calling NetWare’s 
NetBios if one has been installed. 


Then modify PROTOCOL.INI to bind to the 
ODI NDIS interface instead of to the 
individual MAC driver. See the Bindings = 
statements in Figure 5 for an example. 


OS/2 LAN Requester 3.0 


If you are going to install Extended Services 
for OS/2 (ES) on the same machine as the 
multiple requester support, you must install 
ES before installing LAN Services. If you have 
not already installed the LAPS code for 
NetWare support, you must do so before 
installing the OS/2 LAN Requester. Follow the 
installation instructions provided with the 
LAN requester to install it and LAPS for OS/2. 


Once the requester is installed, reboot the 
machine to activate the changes made. Even if 
you do not plan on using OS/2 LAN Services 
but would like to use any other NDIS-based 
communications protocol such as Vines or 
TCP/IP, you must install the LAPS portion of 
the code so NDIS support is available. 


Vines 


The Vines requester is installed with Banyan’s 
VCLIENT program. (At the time of this writing 
VCLIENT was in an incomplete prerelease 
version.) Make sure that PROTOCOL.INI and 
CONFIG.SYS are modified properly. See 
Figure 4 for lines in CONFIG.SYS and Figure 5 
for the section in PROTOCOL.INI needed to 
add Vines support. 


TCP/IP 


TCP/IP is installed with the installation and 
configuration tool provided with the base 
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TI = 30000 

Ti = 500 

T2 = 200 

MAXIN = 1 

MAXOUT = 1 
NETBIOSTIMEQUT = 500 
NETBIOSRETRIES = 8 
NAMECACHE = 0 
PIGGYBACKACKS = 1 
DATAGRAMPACKETS = 
PACKETS = 350 
LOOPPACKETS = 1 
PIPELINE = 5 
MAXTRANSMITS = 6 
MINTRANSMITS = 2 
DLCRETRIES = 5 


2 


; Remove the following section if 
: using the Novell approach to 

: Interoperability. 
[ODI2NDI_nif) 


DriverName = odi2ndi$ 
Bindings = IBMTOK_nif 
; It’s very important to make sure 
: this line is included here. This is 
- either the universal address of the 
: card or your locally administered 
; address, whichever you are using. 
NETADDRESS = “T10005A8FAFi2” 


TOKEN-RING = “yes” 
TOKEN-RING_SNAP = “no” 
ETHERNET_802.3 = “no” 
ETHERNET_802.2 = “no” 
ETHERNET_IT = “no” 
ETHERNET_SNAP = “no” 
TRACE = 0x0 


[VINES_XIF] 


DriverName = NDISBAN$ 
Bindings = IBMTOK_nif 
; Bindings = TOKEN 


(TCPIP_XIF] 


DriverName = TCPIP$ 
Bindings = IBMTOK_nif 
; Bindings = TOKEN 


[IBMTOK_nif] 


DriverName = IBMTOK$ 
ADAPTER = “PRIMARY” 
MAXTRANSMITS = 6 
RECVBUFS = 2 
RECVBUFSIZE = 256 
XMITBUFS = 1 





Figure 5: Example PROTOCOL .INI (continued from page 34) 





TCP/IP product called ICAT. To get file 
redirection with TCP/IP, you must install the 
NFS portion of the package. 


ICAT does not completely install TCP/IP. Two 
lines must be added to CONFIG.SYS, and 
PROTOCOL.INI must be updated to provide 
binding information for TCP/IP. CONFIG.SYS 
(Figure 4) is modified as follows: 


DEVICE=C:\TCPIP\BIN\INET .SYS 
DEVICE=C:\TCPIP\BIN\IFNDIS.SYS 


Add the following section to PROTOCOL.INI 
in Figure 5: 


[TCPIP_XIF] 
DriverName = TCPIP$ 
Bindings = TOKEN 


For performance reasons, it is important that 
the INET.SYS and IFNDIS.SY$ lines in 
CONFIG.SYS at the end of this document 
appear before the NETBIOS.OS2 and after the 
NETBIND.EXE line. 


CONCLUSION 


Interoperability, an important part of today’s 
network environment, is particularly useful in 
an environment in which many separate 
networks exist and in which you want to 
access all resources simultaneously. Separate 
logical networks can be connected on one 
physical network, making all resources 
simultaneously accessible from a single 


; This file is required in the root of 
; your boot drive if you want NetWare 

; interoperability with any of the 

; protocols in Figures 4 or 5 and are 

; using Novell’s interoperability 

; solution. If you are using IBM’s 

; solution, this file is not necessary. 


link support 
buffers 15 4210 


protocol odinsup 
bind token 


link driver token 
frame token-ring 
frame token-ring_snap 





Figure 6: Example NET.CFG 
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Softool: Software Change 
Management On The PC 


by Carlos Caballero 


While the integration of OS/2 2.0 into the corporate 
development environment brings considerable 
benefit to organizations, it is also creating new 
challenges in software change management. 
Software development managers, for example, must 
ensure that all changes to an application are 
properly controlled. This requires an internal 
process to manage the product lifecycle from design 
through maintenance. 


CATEGORIES OF PROBLEMS 


Te years ago, new corporate applications 
were developed under the control of MIS 
departments. Today, PC-based development is 
often done informally, using a variety of 
hardware and software. Uncontrolled and 
undocumented modifications to applications 
or PC configurations can lead to chaos. 


The main barrier to effective software change 
management for desktop systems is a lack of 
awareness that software changes on the PC 
need to be managed as strictly as they are 
managed on the mainframe. Without such 
management, companies can experience 
software glitches that can derail system 
development and maintenance. 
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Many PC developers tend to focus on their 
own activities and operating environments 
without regarding how they affect or are 
integrated with a larger system. While they 
have kept up with technological changes, 
developers do not always see the need to 
document and control changes to their 
applications, or to use software change 
management tools and implementation 
strategies. Now that the majority of 
development platforms are interconnected and 
interactive, individual configuration changes 


often have large-scale repercussions. Carlos Caballero 


CATEGORIES OF TOOLS 


Most software change and configuration 
solutions on the market today are targeted to 
narrow audiences operating on a single 
platform, These tools emerged in the 1970s 
and 80s, before corporations began moving 
toward multiple operating systems and 
interconnectivity. 


Several vendors, for example, offer high-end 
change management and library management 
products for mainframe use only. Other 
vendors of PC version management tools 
provide low to mid-level tools to small 
business environments. Softool Corporation, 
in contrast, supports all major software 
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development platforms including IBM, UNIX, 
Digital, and the IBM PC. 


IMPLEMENTATION 
REQUIREMENTS 


The best place to start planning a change and 
configuration setup is with a plan of action 
that spells out corporate objectives and assigns 
tasks and responsibilities to all personnel 
involved with PC-based applications, 
including those in management, development, 
testing, production, and maintenance. To be 


Adding new version 1.3 to INSTALL TXT [change name = 3RDDRAFT] 





Figure 2: Component management with CCC/Manager 


effective, this plan must determine a 
company’s software change management 
needs, include guidelines and procedures to 
standardize and automate management, and 
preferably operate across the entire 
organization. 


The plan can be pictured as a pyramid, with 
mandatory industry standards at the base. A 
project team should assess these standards and 
determine their impact on software 
development. The goal at this step is to 
maximize the integration of procedures and 
tools and optimize cross-tool communication. 
Next, corporate software requirements, based 
on the number and types of development 
platforms in use, must be created to fulfill 
these standards. The third layer of the pyramid 
features procedures implemented to meet 





corporate requirements. At the pyramid’s peak 
are cross-life cycle tools that help get the job 
done. 


Ultimately, this implementation approach 
keeps managers in touch with developers and 
any changes they make. Managers are also 
kept informed as to why changes have been 
made and application status and location. 
With this setup, it is easy to generate a tracking 
report that notes all changes. 


COMMUNICATION 
REQUIREMENTS 


Communication plays an important role in the 
effectiveness of change management. The 
project team must be made aware of the 
consequences that can result from lack of 
control and of their role in keeping the system 
running smoothly. 


TOOL REQUIREMENTS 


Once the implementation plan is in place, it is 
time to choose the cross-life cycle tool that is 
best for the corporation. Because technically- 
oriented tools are usually limited to 
developers’ use, managers and administrative 
users running them must rely on developers 
for information. 


CCC/MANAGER 


Softool Corp. of Goleta, California has a new 
product, CCC/Manager™ for OS/2, which 
provides more functions than older library 
management tools, while remaining accessible 
to all participants in the cycle. CCC/ Manager 
supports all life cycle stages from development 
to testing to production without sacrificing 
control. It also provides support for the 
baselining and release processes, change 
packaging, turnover management, and 
migration control. 


Features 


Friendliness—CCC / Manager's user interface, 
shown in Figure 1, is fully CUA compliant. 
Everyone involved in the life cycle can use this 
product. 


Component Management—CCC/ Manager for 
the PC lets users store, retrieve, and 
manipulate versions of any kind of 
components from sources to executables, 
spreadsheets, graphics, and so on. Lifecycle 
components may then be checked out, 
changed, and checked in, all in a controlled 
manner. The process of checking an item is 
illustrated in Figure 2. 


Application Management—This layer, unique to 
Softool CCC™ products, allows users to create 
“virtual windows” in the repository of 
versions, each associated with an instance of a 
given application. Those virtual views or 
configurations represent the application as 
viewed from a given life cycle stage, baseline, 
release, concurrent development area, or 
customized application version. By 
automatically updating those views as changes 
migrate through the life cycle, CCC/Manager 
releases users from the technical complications 
and confusion of manipulating error-prone 
branches or application snapshots. 


Package Management—This feature allows users 
to create, manipulate, and migrate changes in 
groups called change packages, which contain 
all elements associated with a problem 
including documents or spreadsheets. With 
change packages, changes can be moved as a 
unit from one staging area to another or 
promoted to an external directory. Extensive 
reporting permits management review of the 
flow of changes. The Package Management 
layer is shown in Figure 3. 


Host Cooperation—CCC / Manager's 
management of life cycles on multiple 
platforms involves two phases. In the first, life 
cycle management must be implemented in all 
connected platforms, with a version of the 
product for all platforms in an enterprise. In 
the second, the control environments are 
connected to each other with Softool’s 
CCC/Bridge™, an add-on to existing 

CCC/ Manager installations that allows 
integration of LAN-based and host-based life 
cycles. Softool’s new version of CCC/ Manager 
for OS/2, however, does not require any 
specific host connection and can run 
independently on OS/2-compatible 
workstations and LANs. 
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SUMMARY 


As downsizing increases, mainframes, still the 
most common host in distributed life cycles, 
are joined by more and more mini- and 
microcomputer servers such as UNIX 
workstations. CCC/ Manager for OS/2, 
configured for multiple environments, covers 
all these platforms. CCC / Manager is also 
available for IBM mainframes (MVS & VM), 
Digital (VMS), UNIX, and Windows. 
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Carlos Caballero, Softool Corp., 340 South 
Kellogg Ave., Goleta, Calif., 93117, (805) 683- 
5777, fax (805) 683-4105. Caballero is product 
manager for Softool. He holds a master’s degree in 
applied mathematics from the University of Central 
Buenos Aires Province, Argentina, and has more 
than 18 years of experience managing all phases of 


the software life cycle. 


For more information about Softool’s 
_ software change and configuration 
“Management products, contact Laurie Mix 


- at Softool Corp., 340 South Kellogg Ave., 
‘Goleta, Calif., 93117, (805) 683-5777, fax 
(805) 683-4105. 
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Testing Client/Server 


Applications 


by Phil Wallingford 


The development of increasingly complex 
client/server applications is bringing to light the 
need for more effective software testing and quality 
assurance. With new GUI applications increasing 
in complexity, testing costs have exploded; major 
software suppliers such as Borland International 
and Lotus report that testers now outnumber 
developers. Concurrently, the audience for GUI 
applications is expanding into the millions, 
multiplying the cost in money and reputation of 
delivering buggy software. 


In the context of these changes, it is tronic that 
software test technology has advanced little since 
the beginning of the computing era; most tests are 
still performed manually. The common myth that 
software can't be tested needs to be rethought, 
restated more accurately as “Software can’t be 
tested using a traditional testing approach.” It 
seems that there can never be enough people 
spending enough time at enough keyboards to 
assure that a piece of software is ready. 


This imprecision can be alleviated through 
improved testing methods, particularly through 
automated testing. To be effective, automation must 
be applied throughout testing, from the test design 
phase to test development to execution. 


This article discusses test automation techniques 
and tools and their applicability to the special 
requirements of client/server computing. 


SOFTWARE TEST AUTOMATION 


Asm way to introduce software test 


automation is to review questions 
commonly asked of those responsible for 
testing, such as: “How many problems have 
you found?” and “How much time have you 
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taken to find them?” Unfortunately, although 
the questioners know that these aren’t really 
the “right” questions, they're the only ones for 
which there are, typically, straightforward 
answers. 


More helpful questions might include: “How 
much of the code is tested? If it’s not fully 
tested, when will the testing be done?” and 
“How reliable is the software? If I field it, 
what's the estimated failure rate?” These 
questions can be answered, but not without 
the application of systematic engineering 
discipline and automated test tools. Test 
automation must first be approached by 
defining the objective criteria used to judge the 
progress of a test, including what data will be 
collected and what analysis will be used to 
determine when testing is complete. 








Phil Wallingford 


There are two fundamental approaches to data 
collection in software testing. The first is to 
collect failure data based primarily on black 
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Figure 1: Test automation system 


box or functional tests and fit the data toa 
software reliability growth model to determine 
the software’s readiness for operation. Several 
different models have been proposed for this 
kind of data collection, based on the use of 
different techniques and statistical methods. 


The second approach is to establish measures 
of testing completeness based on some 
criterion, then collect the associated data to 
measure progress. In this approach, it is 
common to use various coverage measures to 
show how completely the software has been 
tested. Of particular interest are structural (or 
white box) coverage measures such as control 
branch or data flow; functional coverage 
measures are also common, 


Of course, both approaches can be used. Once 
a tester forms a strategy, he or she must 
develop an implementation plan, including a 
set of integrated automation tools. Figure 1 
shows the major elements of a system for 
automating software testing. 


Testers must establish a test repository to save 
test items and measurement data ina 
structured, retrievable way. The volume of 
data required to support automated testing is 
enormous; a modest testing program can 
require tens of thousands of test cases and 
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generate thousands of test incidents, or 
unexpected outcomes. Any test program also 
needs a team of testers who must have 
accurate and timely access to the data. 


The complexity of software programs and the 
tools and techniques used to design them 
makes automation necessary for accurate 
testing. Test design tools can automate test 
generation using control or data flow 
graphing, domain analysis, syntax testing, 
state graphing, or other structured design 
processes. 


Other tools automate test execution (including 
capture and playback), collect data quickly and 
reliably, and save it in the repository. Finally, 
management tools help maintain the 
repository, generate reports, and analyze 
incoming data, answering the questions posed 
previously. 


TESTING REQUIREMENTS 


Client/server applications place special 
requirements on testing methods and tools. 


GUI Concerns 


GUIs such as the OS/2 Presentation Manager 
have become an essential part of most 
client/server applications. These new 
interfaces, however, place an entirely new set 
of requirements on testing techniques. New 
input devices must be recognized; high- 
resolution spatial and color images must be 
examined. Most significantly, GUIs bring 
complexity and freedom to user interaction 
that makes traditional testing obsolete. 
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Reliability 


Most client/server applications are developed 
for critical business functions. An insurance 
company, for example, may use client/server 
technology to process its claims payments. 
Reliability problems in this process can be 
devastating to the company and its customers. 


Unfortunately, the delivery of reliable 
applications on client/server architectures 
presents challenges beyond those of traditional 
host-based applications. In most cases, 
client/server architectures span multiple 
processors that are connected through highly 
layered communications protocols. Some 
processors may be shared while others are 
dedicated. This environment, while attractive 
for its technical merits, is daunting because it is 
difficult to assure its reliable operation. 


Multiuser Systems 


Client/server applications serve many users 
and span large heterogeneous networks. In 
traditional host-based environments, 
multiuser system operation can be reliably 
tested by running user simulators on a central 
processor. In the client/server environment, 
the server processor can be tested with a 
similar approach. The client side, however, 
demands new testing techniques, especially in 
regard to the scheduling and monitoring of 
client software operation, Workstations may 
be distributed across a wide area without 
central control, and there is the problem of 
restarting workstations after fatal errors. 


Repository-Based Test Measurement Systems 


The high volume of testing required for most 
client/server applications demands an 
accumulation and analysis of test data that 
cannot be handled by manual techniques. 
Client test systems need electronic access to a 
central repository to automatically log test 
results as well as the capability for analysis 
and report generation to interpret and present 
them. 


Concurrency 


Access to shared resources must be efficient 
and reliable. Most client/server applications 
share a database, with workstations sharing 


responsibility for maintaining the integrity of 
system resources. Workstations have been 
providing multiuser concurrent processing for 
a relatively short time. Testing techniques 
must verify their ability to perform this 
processing. In addition, the ability of a client 
workstation to manipulate database records 
locally creates new opportunities for 
concurrency errors. 


Performance 


Users of client/server applications expect 
performance at least equivalent to that of 
familiar host-based applications, The flexibility 
of client/server computing’s multiprocessor 
setup, its great strength, will require new ways 
of monitoring and tuning performance. Within 
the workstation, as new OS/2 applications are 
delivered and enhanced their code 
segmentation structure will need tuning. This 
requirement, familiar to large system 
developers, must be adapted for workstations. 
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TOOLS AND TECHNIQUES 
FOR TESTING 


Software Quality Automation supplies test 
automation tools for GUI and client/server 
development. From experience assisting 
customers in delivering major client/server 
applications, the development staff has distilled 
a set of basic requirements that address the 
special needs of client/server testing. 
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Test Execution 


Test Execution 


Test-execution tools are the most ubiquitous of 
all test automation tools. They automate the 
application of test cases to the software under 
test and provide data about software 
performance. Capture/playback execution 
tools, the most common, capture a user’s 
keyboard and mouse operations into a script, 
which is then played back on a later software 
release to verify consistent operation. This test 
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approach is called “regression testing” because 
software is checked to ensure that it has not 
regressed to an earlier state, Capture / playback 
tests are usually black-box tests performed 
during a system test. 


Traditionally, test scripts are saved in some 
proprietary format and are often uneditable. 
However, test scripts must be adapted to 
changes in the software under test. In tools 
that allow testers to edit scripts, the scripting 
language is also proprietary. The language is 
also usually low level, dealing, for example, 
with mouse movements that are difficult to 
interpret, let alone modify, as shown in Figure 
2. These factors combine to make script editing 
tedious at best. 


Newer capture/playback tools, such as SQA‘s 
SQA:Robot™, have advanced scripting by first 
recording the script in a standard scripting 


language and translating the low-level captured 
information into high-level operations, as shown 
in Figure 3. A scripting language should be 
integrated with a standard programming 
environment such as BASIC, C, or REXX. 
Building the scripting capability on a standard 
environment brings the power of a full 
programming tool to test scripting, reduces 
training requirements, and enables testers to 
integrate third-party software packages. 


The scripting language also becomes the 
vehicle for delivering automated tests 
generated not by a user’s actions but by 
automated test generation techniques. Built-in 
test cases allow testers to compare screen 
images, examine output data, verify file or 
window existence, monitor interprocess 
communication, and check file contents. They 
can also integrate user-defined test cases into 
the scripts. Finally, wait states allow the 
software under test to stay synchronized with 
system resources such as network traffic. 


Similarly, testers can track system performance 
and monitor system resources such as 
memory, stack usage, and disk space with test 
execution tools. They can measure 
performance of software under varying system 
configurations. Coupled with test design tools 
that analyze the structure of the software, test 
execution tools can also capture test coverage 
information such as statement, branch, path, 
and data flow. 


Test-execution can be expanded to include 
network testing. In a client/server 
environment, multiuser testing runs test 
scripts simultaneously on a number of client 
workstations. (Script execution can be 
scheduled with any network scheduling 
software.) Test results, including performance 
characteristics, can be accumulated and 
monitored on a server, as in Figure 4. 


Error Recovery 


Error recovery for a client workstation is 
essential for productive client/server testing. 
Error recovery should be available on at least 
three levels. First, the scripting language 
should allow the developer to detect test case 
failures and take appropriate action (for 


example, skip to the next test case). More 


serious or unexpected faults, such as 
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“Adequate” 
must be defined, 
raising the 
question of how 
to determine 
when enough 
testing has been 
done. 


protection violations or stack overflows, must 
be trapped so the system can reset to a known 
state before proceeding. Finally, the test 
environment should be able to recover from 
fatal system crashes with the aid of a hardware 
timer and a bookmark facility (which identifies 
the point of failure) in the test scripts. 


Test execution tools currently address testing 
of the user interface. The loosely coupled 
architecture of client/server applications 
suggests other approaches, elaborated in 
Figure 4. Application building tools can define 
objects with well-developed APIs, while the 
client/sever interface can be specified at 
different levels, such as remote procedure calls 
or SOL calls. Each of these interfaces is an 
attractive “hook,” or connection to monitor the 
software for capture / playback technology. 





Figure 5: Client/server APIs 


Test Design 


Currently, test design tools are the least used 
automation tools, a sign of the immaturity of 
testing methods. (In fact, test design itself 
appears to be absent in many instances, as 
evinced in the saying “Build the test first; 
design it later.”) 


Test design tools will eventually become the 
most important elements of the tool set, 
removing the last large labor component in test 
suite design. They are also the only 
instruments that can generate the large 
numbers of tests, such as data sets, that will 
soon be required for adequate testing. 


But “adequate” must be defined, raising the 
question of how to determine when enough 
testing has been done. Commonly, the 
definition is based on available testing 
resources (such as testing until the promised 
delivery date), with little regard to 
fundamental measures of software quality. 
More scientific measures are based on criteria 
such as branch and path coverage, data flow 
coverage, and reliability. Good test design 
defines the test cases that provide these 
measures. 


Test design can be addressed to either 
functional or structural (typically unit) tests. 
Design automation tools for functional tests 
are hampered by a lack of formal software 
requirements or functional specification 
languages. As a result, test coverage must be 
defined by interpreting natural language 
descriptions. Testers can use automation tools 
to catalogue and organize the test coverage 
points and associated test cases to generate 
coverage completion reports. 


Design automation can also be applied to 
recorded test scripts (generated with a 
capture/ playback tool, for example), especially 
when the scripts exist as a high-level language. 
With a script recorded to populate cells in a 
spreadsheet and verify the results of 
calculation, an automation tool can generate 
hundreds of variations of input-output data 
sets (test cases) that can be read by the script 
during playback. With recorded scripts, it is 
best to describe inputs and outputs in a formal 
syntax (such as Backus-Naur form) and apply 
a general purpose test data generator. 


Structural testing lends itself to automated test 
design, as the software code exists as a formal 
description of how the software operates. 
(How it operates is not necessarily the same as 
how it is meant to operate, but that’s another 
subject.) With this formal description as a 
foundation, structural test design can become 
highly automated. 
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One test coverage approach, relatively easy to 
implement, produces important information 
for performance tuning of client applications. 
Function coverage (as in C functions) mapping 
provides a reasonable, although sparse, means 
of test coverage. Testers can devise a strategy 
for optimizing (segment swapping) 
performance from the generated function call 
tree profile. This tuning will become 
increasingly important in client/server 
computing as applications take advantage of 
virtual memory systems on the client 
workstation. 
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Figure 6: Test repository contents 


Test Repository 


The Test Repository, at the core of the test 
system architecture, is a central facility used to 
store, organize, and validate all information 
necessary to support a robust departmental (and 
ultimately corporation-wide) testing and quality 
assurance program. The Repository also 
provides access to existing source-code libraries, 
enabling automated static analysis, code 
metrics, structural test case generation, and so 
on. Examples of information maintained by the 
Repository are shown in Figure 6. 


The central technology in the Test Repository 
is a robust database management system. All 





test data is cross-referenced through this 
facility to maintain configuration control in an 
evolving product release cycle. For example, a 
tester can make queries to determine which 
test cases will have to be reviewed if a 
particular software module changes. The 
Repository also supports group testing efforts 
with security and record-level locking features. 


SQA delivers all of its products integrated with 
a Test Repository, which all test automation 
tools use as their information back plane. The 
Repository’s data model is fully disclosed; it is 
accessed with published access methods. 


Test Management 


Managing a software test and quality 
assurance program requires a system to 
measure progress and analyze results, The 
system should free testers from tedious clerical 
tasks. The management system should be 
integrated with design and execution tools so 
all can access common data. Test management 
tools maintain the Test Repository and analyze 
and report on stored data, giving quality 
assurance, test, development, product 
management, and customer service staffs a 
unified view of the status of a testing program. 
Toward this goal, SQA has delivered the 
industry’s first PC-based test management 
system, SQA:Manager™, which is fully 
integrated with SQA’s Test Repository and 
other automation tools. 


SUMMARY 


As development organizations build 
client/server systems, testing practices need to 
be reviewed and adapted to automated 
techniques. Test automation is becoming 
essential to deliver reliable client/server 
applications. 


Phil Wallingford, Software Quality Automation, 
1 Parker St., Lawrence, Mass., 01843, (508) 689- 
0182. Wallingford founded Software Quality 
Automation in 1990. He has over twenty years 
experience in software development and has led 
development teams working on CAD/CAM 
product development and multimedia applications. 
Wallingford can be reached at the address above or 
on CompuServe. 
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Client/Server 
Testing in the GUI and 
Client/Server World 


by Marvin Tener 


It is no news to OS/2 developers that testing in a 
GUI environment is a difficult task. As developers, 
we are now at the point where our ability to build 
systems far outpaces our capacity to reliably test 
them. At the same time, there is increasing pressure 
on commercial product developers and corporate 
MIS departments to produce higher quality 
software. If there is one thing being hammered 
home again and again, it is that users have had it 
with serving as unwitting beta sites. 


GUI client/server applications are becoming more 
and more popular with users and developers. Such 
applications are, after all, powerful, flexible, and 
easy to use. Ironically, though, the very features 
that give GUI client/server applications their appeal 
are what make them so difficult to test. 


THE GUI CHALLENGE 


Wi: GUIs, what the user perceives as 
freedom—moving a mouse, clicking 
on icons, opening multiple windows—the 
software tester experiences as random 
behavior, difficult to model and predict. The 
tester, moving a mouse across the desktop and 
clicking, is obscured from the workings of the 
operating system and from what the 
application sees in relation to what he or she is 
doing. The tester has little control over certain 
actions, such as windows repositioning 
themselves and coming up in new areas on the 
screen. 


The entire model presented by GUIs is far 
different from the hierarchical model available 
in the character-based world. To reach a screen 
at which data entry will occur in the DOS and 
mainframe environment, a user has to wade 


through several levels of menus. In this 
environment, an application takes a piece of 
information from the screen (for example, the 
highlighted first letter of a menu pick), 
performs a task, completes it, and grabs the 
next piece of information when the application 
is ready for it. 


Applications under GUIs are event driven, 
with applications responding to events that 
can come from anywhere: a keyboard entry, 
mouse click, dynamic data exchange, object 
linking and embedding, information from 
another application, and so on. The difference 
between character-based and event-driven 
processes has been termed “pull-push,” with 
the character-based model pulling in 
information and the event-driven model 
having information pushed at it. 


In determining what this means for an 
application tester, it may be clearer to define 
the difference using baseball as a metaphor. In 
the character-based world, the application is 
the pitcher, controlling the tempo of a game by 
throwing the ball when it is ready to do so. In 
the event-driven world of GUI, the application 
is the shortstop, scrambling after balls hit in its 
direction. Admittedly, this analogy is 
imprecise: a pitcher can toss a wild pitch or get 
hit by a broken bat, and a good shortstop will 
have some sense of the hitter, game strategy, 
and so on. On balance, however, it is the 
pitcher who more often controls the game and 
whose activity is easier to predict and prepare 
for, and the shortstop who must remain alert 
for possible action. 


Under GUI, there is the added complexity 
surrounding available system resources. 
Testers in the DOS and mainframe world are 
mainly concerned with disk space, file 
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time testing the 
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application focus 
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user interface, 
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handles, and memory. Beyond that, there are 
limited resources to worry about. In the GUI 
world, there are additional resources—such as 
pens, window handles, and device contexts— 
that may be in use by one or more applications. 
A GUI tester must consider many more 
complex resources, 


THE CLIENT/SERVER CHALLENGE 


With networked applications, the testing 
landscape becomes more difficult as 
applications are moved from the controlled 
mainframe environment into the more open 
world of the client/server domain. It is no 
longer sufficient to test the unit functionality of 
software, but is now necessary to determine 
how it will act in a complex environment that 
may contain disparate applications running 
under multiple versions of operating systems 
across multiple platforms. 


In addition to the complexity of testing itself, 
there is the additional issue of fixing a problem 
once a system has been installed. In the “old 
days,” it was relatively easy for an MIS 
director to perform a test run when 
development finished with the executable, 
which, after all, would reside in just one place. 
If a problem occurred, it was relatively simple 
to roll back to a stable version of an 
application. In the client/server world, in 
which applications may be distributed over 
thousands of machines at many different sites, 
the actual delivery of the system to those 
machines is a physically daunting task. If there 
is a problem, it is harder to roll back to a stable 
version of an application. 


THE OPERATING SYSTEM 
CHALLENGE 


Intertwined with the GUIs and networks on 
which they run are the powerful operating 
systems that hold everything in place, which 
can also present problems for testers. In the 
DOS world, operating systems were thin in 
their support, offering little beyond the ability 
to read and write files, allocate memory, and 
put a character to a screen. Those charged with 
testing an application were involved primarily 
in testing the code that was being generated, 
with little attention paid to the underlying 
operating system or to the user interface. 


OS/2 does a lot more than DOS, and is far 
more robust. OS/2 2.0 also offers a range of 
features for developers: standard controls, 
multithreading, resource management, 
elaborate user interface support, and network 
and mainframe communication facilities. In 
addition to testing basic application code, 
testers now need to spend more time testing 
the interaction of application focus points with 
the user interface, operating system, and 
network. 


TESTING IN THE 
DEVELOPMENT CYCLE 


As applications have become more complex, the 
role of those responsible for software testing has 
grown to that of “quality assurance 
professional.” In mainframe development, the 
rule of thumb was one quality assurance person 
for every five to 10 software engineers. We are 
now seeing a marked shift in these ratios. At the 
Software Testing Analysis & Revue conference 
in Las Vegas, Nevada, in May 1992, David 
Moore of Microsoft’s Worldwide Product 
Division noted that in his division there are two 
quality assurance professionals for every three 
developers; at some points during the 1-2-3 
Windows" release at Lotus, there were two 
quality assurance professionals for every 
developer. These dramatic shifts have occurred 
among bath independent software vendors and 
large corporations. 


As testing grows in importance, tools that 
assist quality assurance are emerging. New 
tools that address software testing and 
maintenance represent a change from those 
released during the 1980s that focused 
primarily on the application analysis, design, 
and coding aspects of the application 
development cycle, such as CASE, fourth 
generation languages, C++, and object- 
oriented programming. 


TEST PROCESSES 


Softbridge currently produces a software 
testing product, the Softbridge Automated Test 
Facility™ (ATF) for testing stand-alone and 
client/server OS/2 and Windows applications. 
Among the first to develop large scale GUI 
client/server systems in the mid-1980s, 
Softbridge worked with IDS/ American 
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Express to build a support system for its 
financial planners. The initial system was a 
three-tiered architecture made up of DOS- 
based front-ends, DOS application servers, and 
mainframes. Over time, the system grew to a 
point at which OS/2 replaced DOS as the 
front-end and server operating system. During 
implementation of this system and others for 
Nedlloyd Lines and MCI, Softbridge 
encountered problems that led to the 
development of ATF. In doing so, the 
company came up with working requirements 
for a testing tool: consistency, repeatability, 
unattended operation, and networking ability. 





ATF Executive: 
OS/2 PM 





Figure 1: ATF architecture 


Consistency 


Testing consistently means being able to codify 
or script a test case, either through a scripting 
language or through capture / playback 
recordings of user interactions with an 
application. The best-case scenario is a testing 
product that provides the capability of 
blending tape recordings and 
programmatically created scripts. 
Capture / playback allows testers to quickly 
create a set of test cases, Programmatic 
development of scripts lets testers develop 
generic test cases that can evolve over time 
and build test cases before software is finished. 


[f tests are done manually and a fault or an 
error occurs, it is difficult for testers to 
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remember exactly what they were doing at the 
time of the error, unless they were following 
an explicit script. (This pretty much leaves out 
using the mouse or behaving like a normal 
GUI user.) With scripted test cases, testers can 
present an exact record of their actions. 


Repeatability 


Studies have shown that during the release of 
an application, software moves between 
development and quality assurance an average 
of six to 15 times. As the release date nears, 
considerable pressure is placed on testers to 
restrict their activity to areas where change has 
occurred. Sound testing practice calls for 
running a full set of regression tests on an 
application each time a change is made, 
identifying effects that cannot be uncovered if 
only the changed code is fully tested. With 
automation, once you incur the startup costs of 
codifying the test suite—admittedly, a more 
time-consuming process than simply running 
through the tests manually—testers are 
guaranteed the ability to run their entire test 
plan no matter where they are in the 
development cycle. 


Unattended Operation 


As a measure of testing thoroughness, code 
coverage (that is, the percentage of code in an 
application that has been tested) is not as 
important in the GUI world as in the 
mainframe world. Considerable state 
information that cannot be captured through 
code coverage is incorporated into GUI-based 
operating systems. Many testers are shifting to 
mean time to failure to judge the completeness 
of testing. Unattended testing facilitates 
longer-term tests to determine mean time to 
failure, uncovering obscure problems that 
might not appear in the field for many months 
or might be difficult to replicate. 


Networking Ability 


Only a networked test tool can easily replicate 
real-world client/server conditions. 
Networked testing can coordinate 
client/server activities such as testing for load 
conditions or lock-out when 20 operators are 
using a system simultaneously. With 
networked testing, you can also modify an 
environment by changing screen resolutions, 
memory configurations, or drivers. 
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SOFTBRIDGE AUTOMATED 
TEST FACILITY 


The Softbridge ATF was designed to satisfy 
the previous four criteria. It consists of two 
major software components, the Executive and 
the Controller, that mirror the client/server 
environment. With its Executive, ATF 
provides a command center from which testers 
can view and control the operation of complex 
distributed applications on up to 50 target 
machines driven by ATF Controllers, as shown 
in Figure 1. Under the direction of the 
Executive, an OS/2 Presentation Manager 
application running under either OS/2 1.3 or 
2.0, ATF can run simultaneous tests on OS/? 
or Microsoft Windows applications, with the 
Controllers acting in concert to run the 
applications being tested. 


ATF can also drive stand-alone applications on 
multiple hardware platforms simultaneously, 
for increased testing throughput. It is this one- 
to-many configuration that allows users to 
implement comprehensive test cases that 
simulate field conditions for client/server 
applications. The number of complex tests that 
can be implemented with ATF far exceeds 
those that can be orchestrated with human 
testers. This is because ATF’s architecture 
provides a flexible framework for complex 
configurations that allow users to increase the 
volume of tests they can perform, to 
orchestrate tests of multiuser applications, and 
to isolate tests to optimize their ability to run 
unattended. 


ATF Executive 


The multitasking ATF Executive is an 
integrated test control center from which tests 
on target machines (Controllers) are governed. 
Test scripts are written at the Executive and 
run against the applications being tested on 
the remote machines. The Controllers then 
report test results to the Executive, where they 
are reviewed and analyzed with the Results 
Viewer. 


Distributed Test Language (DTL)—The core of 
the ATF system and the key to ATF’s ability to 
run tests consistently and repeatedly, DTL is 
the language ATF uses to codify test cases into 
executable test scripts that restore data to a 
given state, run tests from a central point of 
control, and save test results in a central log file. 








Tape Capture/Playback—ATF records and, on 
playback, recreates a user’s keyboard and 
mouse interaction with the applications being 
tested. The context-sensitive recorder moves, 
sizes, and repositions icons and windows 
ahead of playing tapes. ATF can play tapes 
back at variable speeds, particularly useful 
when a test plan calls for running large 
quantities of data against a system as quickly 
as possible. In areas such as stress testing, this 
can save hours. ATF’s tapes can also be 
parameterized and merged with data to 





# Connect to workstation(s) under test 
connect gsos2 


#Start application to test —the 0S/2 Systems Editor— 
appstart e 


#Select option from menu bar 
menuselect(app, “File|New”) 


#Enter text 
play keys “Softbridge, Inc.” 
play keys “<enter>” 
play keys “ATF Means Quality Software” 


#Select option from menu bar 
menuselect (app, ”File|Save” ) 


#Enter text to name the file being saved 
play keys “SBATF” 
play keys “<enter>” 


#Exit the application 
appexit e 





Figure 2: SCRIPT 


#082: Sets the Environment 
SET SYSTEM TO 0S2 
SET COUNTRY TO US 
SET CAPSLOCK OFF 
SET pigeeyaala 
il NUML OFF 
ET MO “in Wy TO 2 


satin Sa 


#Sets up ‘the De lt 
WINDOW ia MH 
MODULE Pe 
TITLE “e.EXE - Untitled” 

END WINDOW 


CLASS “EHXMAIN” 


Figure 3: TAPE (continued on page 58) 
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WINDOW DESKTOP_MANAGER 
MODULE “PMEXEC”, CLASS “StarterWindow” 
TITLE “Desktop Manager” 

END WINDOW 

WINDOW GROUP 
MODULE “PMEXEC”, CLASS “StarterWindow” 
TITLE “Group - Main” 

END WINDOW 


WINDOW ATF 
MODULE “EXEC”, CLASS “ATF_MASTER” 
TITLE “ATF” 

END WINDOW 


#Resizes the windows and icons 


SELECT E.EXE 
SIZE NORMAL (76,152) TO (573,472) 


SELECT DESKTOP_MANAGER 
SIZE ICON (539,36) TO (571,68) 


SELECT GROUP 
SIZE ICON (439,36) TO (471,68) 


SELECT ATF 
SIZE ICON (239,36) TO (271,68) 


SELECT E.EXE 

ACTIVATE 

DELAY 0, MOVE (25,35) #Mouse movement 
DELAY 0, LEFTDOWN (25,35) #Mouse button down 
DELAY 0, MOVE (25,35) 

DELAY 17, MOVE (25,37) (26,39) (26,41) (26,41) (26,42) 
DELAY 9, LEFTUP (25,36) #Mouse button up 
DELAY 5, “Softbridge Inc.” #Entering Text 
DELAY 15, “<Enter>” 

DELAY 5, “ATF Means Quality Software” 

ACTIVATE 

DELAY 53, MOVE (27,31) 

DELAY 0, LEFTDOWN (27,31) 

DELAY 0, MOVE (27,31) 

DELAY 0,  LEFTUP (27,31) 

ACTIVATE 

DELAY 54, MOVE (32,90) 

DELAY 0, LEFTDOWN (32,90) 

DELAY 0, MOVE (32,90) 

DELAY 0, LEFTUP (32,90) 


SELECT SAVE_AS #Saving the file 
SIZE NORMAL (82,128) TO (567,427) 
DELAY 122, “S” 

DELAY 12, “B” 
DELAY. 5, *“K* 
DELAY. 4, *T* 
DELAYS. 5 *E* 
DELAY 23, “<Enter>” 














Figure 3: TAPE (continued from page 57) 





generate tests for field oriented applications. 
All tapes are fully editable. 


Result Viewer—The result viewer is a 
Presentation Manager application used to 
view result logs and window text files. 


Bitmap Viewer—The bitmap viewer is a 
Presentation Manager application that lets 
users view and compare bitmap files. A test 
bitmap can be compared to a baseline bitmap 
to evaluate application performance using 
multiple exclusion and inclusion regions. 


Text Screen Viewer—The text screen viewer is a 
Presentation Manager application that lets 
users view and compare OS/2 VIO text 
screens. A test screen can be compared to a 
baseline screen to determine application 
performance using multiple exclusion and 
inclusion regions. 


Power-Off and Power-On Support—The optional 
Omega Power Control feature allows ATF to 
recycle a machine’s power after a catastrophic 
software failure, enhancing ATF’s ability to 
run tests unattended. Even if this option is not 
exercised, ATF’s architecture, with the 
Executive completely external to the test 
workstation, promotes unattended testing. On 
encountering a failed test, the Executive 
proceeds to the next script, loading and 
starting applications and test tapes as needed. 


ATF Controller 


An ATF Controller receives DTL commands 
from the Executive and runs the application to 
be tested on the Controller machine. Results of 
the tests are then sent from the Controller to 
the Executive. 


Controller Features 


Communication Between Executive and Test 
Applications—The Controller manages the 
interaction between the Executive, which 
orders specified tests to be performed with 
DTL, and the application being tested against 
which those tests are run. The presence of 
Controller software on a test workstation gives 
the Executive complete control over that 
machine. 


GUI State Restoration—One of the most 
difficult problems in GUI test automation is 
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restoring a test’s beginning state for each 
instance of a test run. The ATF Controller 
provides sophisticated GUI state restoration 
capability. For example, before running a tape, 
the Controller ensures that an application's 
windows are of the same size and in the same 
position as they were when the original 
recording was made. 


Satellite Tape Factory—In addition to driving a 
Controller from the ATF Executive, users can 
use a Controller as a satellite tape factory, 
permitting tapes to be recorded and played 
back without intervention from the Executive. 
These tapes, which may later be uploaded to 
the Executive for use in ATF scripts, are 
equivalent to tapes created directly through 
the Executive. The satellite user interface can 
also be used to start applications and snap 
bitmaps and window text. 


As noted previously, ATF supports 
programmatic and tape record / playback 
approaches to testing. Although most of ATF’s 
users follow a combined approach, a rule of 
thumb is that a capture/ playback facility lets 
users get up and running with ATF very 
quickly. Users without any programming 
background can create a library of tapes that 


will become the basis for substantial test suites. 


A programmatic approach requires a higher 
level of programming ability, but DTL has 
proven easy to use. While it supports 
sophisticated programming through its range 
of commands and functions, in its simplest 
form, non-programmers can build 
straightforward test cases. Figure 2 illustrates a 





simple ATF script that takes the programmatic 
approach, running the OS/2 editor 
application; Figure 3 is an ASCII version of a 
tape recording of the same user session. 


While a tape may be easier to create (ATF’s 
recorder does the work in terms of figuring out 
what is going on with an application), the 
result is more complex to edit. While simple, 
Figures 2 and 3 do illustrate the rudimentary 
ATF commands for connecting to the machine 
on which a test will occur, starting an 
application, playing keys, and making a menu 
selection. 


The results of a test, whether done 
programmatically or via tape, are logged so 
testers can determine its success or the point of 
failure. The advantage of using scripts and 
tapes is that once a bug is encountered and a 
fix is made, a test can be rerun automatically, 
unlike with manual testing, which requires the 
tester to sit down and run through the 
application again. 


Whether OS/2 developers are testing with 
ATF or not, the bottom line is that anyone 
building GUI networked applications cannot 
ensure software quality with only the brute 
force of manual testing. The testing future 
belongs to an increasingly automated 
approach to testing increasingly sophisticated 
applications. 


Marvin Tener, Softbridge Microsystems Corp., 
125 CambridgePark Dr., Cambridge, Mass., 02140, 
(617) 576-2257. Tener has over 25 years experience 
in software development and testing. Before 
assuming his current post as director of 
development for Softbridge, he was the 
development director of several major client/server 
systems implemented by Softbridge Consulting. He 
has also worked as an independent consultant and 
vice president of technology at Interactive Data 
Corp. Tener holds a B.A. in mathematics from the 
University of California at Berkeley. 
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details on this inside-information event for securing, networks in the new open environment. 
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4 YES, I will attend NETSEC "93. Please register me. 


JUNE 21-23, 1993 


) I’m not ready to register yet, but please send me a conference catalog. CAPITOL HILTON 
WASHINGTON, D.C. 
FAX TO: 
(415) 905-2218 
NAME TITLE MAIL TO: 
CSI CONFERENCE 
COMPANY REGISTRATION 
600 HARRISON ST. 
ADDRESS MAIL STOP SAN FRANCISCO 
CA 94107 
CITY STATE ZIP OR CALL: 


(415) 905-2626 
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OS/2 2.0 Video Systems: 
Structure and Behavior 


by Weldon Adair 


OS/2 2.0 can run 16- and 32-bit OS/2 applications 
as well as Windows and DOS applications, in either 
windows on the desktop or full-screen sessions. 
Applications run differently in each format, and each 
format presents its own advantages. Some full screen 
DOS and Windows applications, for example, may 
run at different resolutions under certain 
circumstances than they do on the Presentation 
Manager desktop. 


This article explores the OS/2 session architecture 
and how it is supported by the OS/2 display drivers. 
It also covers the conditions under which programs 
may become suspended due to video operations and 
how to run full-screen Windows applications when 
the desktop is in medium resolution. 


RUNNING DOS AND WINDOWS 
APPLICATIONS ON OS/2 


() 2 has always been able to run 
multiple OS/2 applications. Under 
OS/2 2.0, users can also run multiple DOS and 
Windows applications, most of them in 
windows on the OS/2 Desktop. This increased 
flexibility results in part from OS/2 support of 
the 386 architecture processor's virtual 8086 
(v86) mode in a 32-bit paged address space. 
The v86 feature is used to construct virtual 
DOS machines (VDMs) that allow DOS 
applications to coexist with the protected- 
mode applications of OS/2. Using virtual 
device drivers (VDDs), which provide the 
resources of a virtual PC to the DOS program, 
a VDM runs in its own session like any other 
OS /2 process. 


Only the display physical and virtual device 
drivers will be discussed in this article. For a 
fuller understanding of how OS/2 supports 


Multimedia 


VDMs, see The Design of OS/2 (Deitel and 
Kogan, 1992). 


DOS and Windows Applications 
in Full Screen 


VDDs for display handle the output of DOS 
applications to the actual display hardware. 
Windows output is handled both by the VDD 
and by cooperation between the OS/2 physical 
device driver (PDD) and the Windows device 
driver. Understanding how the VDD provides 
support to an application running in full- 
screen mode helps us understand how the 
VDD supports output of a DOS application to 
a window. 





Weldon Adair 


DOS or Windows applications running in full- 
screen mode in the foreground fill the entire 
screen, obscuring the view of the OS/2 
desktop. Only one full-screen application can 
access the display at any one time; only one 
application, therefore, is actually accessing the 
display hardware. 


VDM: Virtual 
DOS Machine 


VDD: Virtual 
Device Driver 
PDD: Physical 
Device Driver 


Under most circumstances, the VDD provides 
a virtual display to the application running in 
the VDM. But with an application in full- 
screen mode, the actual display receives 
exactly the same output generated by the 
application. In this situation, the VDD can be 
thought to have turned the display hardware 
over to the DOS application or Windows 
device driver. 


But if the VDD truly turned over all display 
hardware, a DOS application or Windows 
device driver could put the display into a state 
unknown to and unsupported by the OS/2 
PDD. To protect the system, the VDD must 
capture the state of the display hardware 
before “surrendering” it to uncontrolled 
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Upon returning 
control to the 
desktop, the 
VDD changes 
modes of 
operation. 


In actuality, a VDD never completely 
surrenders the hardware to an application 
running ina VDM. Under certain 
circumstances, the VDD may allow the 
application some direct access to the hardware; 
however, the VDD always returns the display 
to the OS/2 desktop in the condition expected. 
Usually, the VDD intercepts all VDM attempts 
to directly access display hardware and BIOS 
calls. In some cases, the VDD saves 
information and updates the display hardware 
as an application is given focus. At other times, 
the VDD simply updates the display 
hardware. 


Upon returning control to the desktop, the 
VDD changes modes of operation. In its new 
mode, it continues to receive input from the 
VDM application but does not allow direct 
access to the hardware. 


DOS and Windows Applications in Windows 


When a DOS application is run in a window 
on the PM Desktop, the VDD intercepts all 
VDM application attempts to output directly 
to the display hardware. In this case, most of 
the hardware function is emulated by the 
system and then passed to the PDD. Windows 
applications run in a window on the Desktop, 
in contrast, make use of cooperation between 
the PDD and the special “seamless” Windows 
(WIN-OS/2) device driver. 


There are limitations on DOS graphics 
applications run in Windows on the PM 
Desktop. DOS graphics applications must not 
operate at a higher video resolution than that 
of the PM Desktop, and software cannot 
emulate a higher-resolution mode than that of 
the display. If a DOS graphics application 
attempts to set an unsupported mode, the DOS 
VDM is suspended. 


If a DOS graphics application manipulates the 
display palette in full screen mode, it may not 
have the desired appearance in a window. 
While the VDD maps the DOS application 
colors to the PM Desktop palette with the 
closest fit possible, there may be slight color 
variations because of the transfer. If a DOS 
graphics application uses the mouse to control 
the cursor, you may have to change the DOS 
settings MOUSE_EXCLUSIVE_ACCESS. DOS text 
applications can be in any of the supported 


text video modes; text modes are emulated in 
graphics mode when run in a window. 


In a window on the PM Desktop, Windows 
applications run very differently than DOS 
applications. The VDD for Windows in a PM 
window (VWIN.SYS.) is slightly different from 
the DOS VDD, providing limited 
addressability to a small set of PM routines 
and data and hardware serialization services. 
The special “seamless” WIN-OS/2'™ device 
driver and the OS/2 PDD are aware of each 
other, coordinating their activities through a 
semaphore and sharing access to the display 
hardware. The WIN-OS/2 display driver 
actually “owns” a piece of the display. Because 
this mode of operation requires that the WIN- 
OS/2 device driver and the OS/2 PDD 
cooperate, they must be used in pairs. Older 
OS/2 and Windows display drivers that have 
not been modified to coordinate their activities 
cannot run WIN-OS/2 in a window. 


BACKGROUND EXECUTION OF 
GRAPHICAL APPLICATIONS 


When a DOS application is switched from full- 
screen foreground to background operation, it 
can no longer have the direct access to display 
hardware it enjoyed in the foreground. In this 
case, the VDD restores the hardware to the 
state it was in just before the DOS application 
was given control of the full screen. The VDD 
also begins to intercept all the DOS 
application's attempts to access the display 
hardware, using the intercepted information to 
update a virtual display. Some operations that 
can be done by a DOS application in a full- 
screen session are not emulated; if the DOS 
application attempts one of these operations, 
the VDM is suspended. 


When a DOS application run in a window on 
the PM Desktop is switched to the 
background, no great changes are made, as the 
VDD is already intercepting the application’s 
attempts to access the hardware. The biggest 
change in this situation is that part of the 
virtual display is no longer displayed on the 
PM Desktop. 


When a WIN-OS/7? session is switched from 
full-screen foreground to background 
operation, display drivers provided for WIN- 
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OS/2 full-screen sessions suppress all 
background write operations but allow the 
WIN-OS/2 program to continue to run in the 
background. If the session is switched to the 
foreground again, the program is prompted to 
redraw. When a WIN-OS/2 application 
running in a window is switched to the 
background, the seamless WIN-OS/2 device 
drivers suppress writing to the display ina 
manner similar to that of the full-screen device 
drivers. 


Windows device drivers not provided for 
WIN-OS/2 full-screen sessions may not 
suppress background writing to the display. If 
they do not, the WIN-OS/2 session may be 
suspended in the background. 


High-Resolution WIN-OS/2 in 
Full-Screen Mode 


In the initial release of OS/? 2.0, WIN-OS/2 
window sessions are supported in VGA mode 
only. For Windows users who depend on 
higher-resolution applications, this limitation 
may seem unacceptable. However, there is a 
way to run WIN-OS/2 windows sessions and 
PM Desktop (Workplace Shell) in VGA mode, 
while running higher-resolution Windows 
applications in full screen mode using the 
SYSTEM.INI and WIN.INI files. 


In the SYSTEM.INI file (found in the 
0S2\MDOS\WINOS2 directory), there is an entry 
specific to WIN-OS2 windows sessions, 
sdisplay.drv, used to designate the WIN-OS2 
windows session video device driver. (The “s” 
in its name stands for “seamless.”) 


The SYSTEM.INI file also contains the 
display.drv entry from Windows. At OS/2 2.0 
release time, the swinvga.drv was the only 
WIN-OS2 windows session video device 
driver available from IBM. 


As you might guess, display.drv designates 
the use of the full screen WIN-OS2 video 
device driver. If display.drv points to a high 
resolution device driver that supports installed 
hardware, full screen WIN-OS2 will run using 
that driver. This configuration provides the 
best of high-resolution Windows and seamless 
WIN-OS2. 


The following section presents a detailed step 
by step procedure for using this feature. This 


section assumes that the reader is not familiar 
with the SYSTEM.INI and WIN_INI files. 


These instructions should be followed very 
carefully. If caution is not observed, it is 
possible to render inoperable seamless and full 
screen WIN-OS2 sessions. 





The first step is to install OS/2 for medium 
resolution (VGA). After this is done, it is very 
important to make two backup copies of the 
SYSTEM.INI and WIN.INI files, one to a 
floppy disk or tape and the other to the 
0S2\MDOS\WINOS2 directory. 





It is assumed that a disk or tape backup copy 
have been made; following are instructions for 
backing up to the directory. 


¢ Back up the SYSTEM.INI and WIN.INI files. 


* Open an OS/2 window from the Command 
Prompts folder in the OS/2 System folder. 
At the [C:\] prompt, input: 


[C:\]cd\os2\mdos\winos2 
[C:\os2\mdos\winos2]copy win.ini win.bak 
1 file(s) copied. 
[C:\os2\mdos\winos2]copy system.ini 
system. bak 
1 file(s) copied. 


® Once the SYSTEM.INI and WIN.INI files are 
safely backed up, proceed with modifications. 


Before you make the changes to the files, it is 
best to make sure all desired high-resolution 
Windows device drivers and fonts are loaded 
on the system. 


Check the \os2\mdos\winos2\system directory for 
the desired high resolution display device 65 
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[C:\Junpack a:symbolg.fon 
a:SYMBOLG. FON 
- \0S2\MDOS\WINOS2\SYSTEM\SYMBOLG. FON 
0 file(s) copied. 
1 file(s) unpacked. 


SYMBOLG.FON 
TMSRG.FON 
COURG.FON 
HELVG.FON 


Figure 2: Unpack FON files 


[C:\Junpack a:winxga 
a: WINXGA 
- \0S2\MDOS\WINOS2\SYSTEM\XGA.DRV 
~ \0S2\MDOS\WINOS2\SYSTEM\XGASYS. FON 


~ \0S2\MDOS\WINOS2\SYSTEM\XGAOEM. FON 
~ \0S2\MDOS\WINOS2\SYSTEM\XGAFIX . FON 
0 file(s) copied. 
4 file(s) unpacked. 


Figure 3: Unpack driver 


fixedfor.fon=vgafix.fon 
oemfonts. fon=vgaoem. fon 
fonts. fon=vgasys.fon 


For XGA, these entries should be changed to: 


fixedfor.fon=xgafix.fon 
oemfonts.fon=xgaoem. fon 
fonts. fon=xgasys.fon 


In WIN.INI, these entries will need to be changed: 


Symbol 8,10,12,14,18,24 (VGA res)=SYMBOLE.FON 
Helv 8,10,12,14,18,24 (VGA res)=HELVE.FON 

Tms Rmn 8,10,12,14,18,24 (VGA res)=TMSRE.FON 
Courier 10,12,15 (VGA res)=COURE.FON 


Change this to: 


Symbol 8,10,12,14,18,24 (XGA res)=SYMBOLG.FON 
Helv 8,10,12,14,18,24 (XGA res)=HELVG.FON 
Tms Rmn 8,10,12,14,18,24 (XGA res)=TMSRG.FON 
Courier 10,12,15 (XGA res)=CDURG.FON 





Figure 4: Modify WIN.INI file 











driver. This example uses the XGA.DRV 
device driver. Checking the directory reveals 
that this driver is not loaded. (If the system 
was installed in high resolution mode and had 
a selective install to return to medium 
resolution mode, the driver may be loaded 
already. A description of this approach is 
given below.) 


Retrieving the device driver and fonts from the 
installation disks may involve a bit of hunting. 
Because the OS/2 build system is packed to 
optimize disk space and use as few disks as 
possible, the files may be found on any disk 
from number six to number 15. 


For XGA, search the disks for *XGA* and *G.FON, 
as shown in Figure 1. 


In the example in Figure 1, no XGA drivers 
were found on the disk, but one font file was. 
Although the font file is not part of a bundle of 
files, it still must be unpacked. 


As the files are packed with their standard 
target directory coded into the packed file, 
running the unpack utility will copy the file to 
the proper directory on the system disk, as in 
Figure 2. Eventually the WINXGA file, 
containing the WIN-OS2 XGA.DRV and three 
XGA fonts, is found using the dir a:*XGA 
search, as in Figure 3. 


With all required driver and font files on the 
system disks, the next step is to modify the 
SYSTEM.INI file. Edit the SYSTEM.INI file and 
find the line: 

display .drv=vga.drv 


This line tells WIN-OS2 which device driver to 
use in full screen sessions. Change this line to 
point to the high-resolution device driver 
unloaded in the previous steps. In this case, 
the device driver is XGA.DRV. The modified 
line should look like: 

display .drv=xga.drv 


Font entries in both SYSTEM.INI and WIN.INI 
should be changed. Figure 4 lists the entries for 
SYSTEM.INI. 


Once these changes have been made and the 
files saved, the system is ready to run seamless 
WIN-OS2 applications in VGA mode and full- 
screen WIN-OS2 applications in high- 
resolution mode. 
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For a full description of background 
execution of DOS and Windows graphical 
application programs, see the OS/2 2.0 
Compatibility Information Booklet (IBM Doc. 
41G8276), included in the documentation 
shipped with OS/2 2.0. 


CAPTURE YOUR SCREEN 
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| PrntScrn'™ is THE One-Step Screen Image Utility 
| : for copying a graphics image from the Workplace 
Shell screen to a LAN or locally attached printer, to 
the Clipboard, or to a disk file. The screen images 
appearing in this publication were captured and 
processed using the PrntScrn utility. The capture 
Operation can be initiated from the keyboard (by 
pressing the print-screen key), from the mouse, or 
from another program. The captured image area 
can be the entire screen, current active window, 
current active client area, selected window, selected 
client area, or specified rectangular area. Disk file 
formats include PM Metafile, PM Bit Map, PCX, 
TIFF, GIF, and WPG. The "Color Mapping" 
feature provides the control needed to produce 
quality printed images from color screen images. 
PrntScrn has clipboard Viewing, Printing, 
Exporting, & Importing capabilities for Bit Maps, 
Metafiles, and Text files. PrntScrn includes a 
Screen Blanker and a digital Date & Time 
"information bar". PrntSern is priced at $115 and 
is available from major software resellers, 
or contact MITNOR Software. 
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MITNOR Software 
28411 E. 55th Street 
Broken Arrow, OK 74014 


Phone: (918) 357-1628 
Fax: (918) 357-2869 
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Information at your fingertips. Solutions that will, yes, make your job easier. 
It sounds like a cliché. But when you have a good So no matter what your database specialty, you'll 
magazine in your hands the cliché becomes a reality. lind a subscription to Database Programming © 
Every issue of Database Programming & Design Design to be a real bargain. And at twenty percent off 


puts information and solutions at your fingertips. the regular subscrip- tA 
Solutions that will increase your database performance, tion price, this bargain [fj 


reduce backlog and speed applications development. is now a real steal. Programming & Design 


Solutions! 


How can | possibly lose? 


J Yes! Please start my tull-year subscription to 
Database Programming & Design for $37.00-a 21% savings. 3 Eas Ways 
To Subscribe! 














If | become dissatisfied with Name. ae Tile 
| atabase Prosramming & Design ee @ BY PHONE: 1-800-289-0160 
at any time, | may cancel my oan | ee = 
subscription and receive a full Wddaee Cite — BS BY FAX: 1-415-905-2233 
refund of my $37.00 investment. | ga. 
Check State/Province —___________ Zip/Postal Code ———w = BY MAIL: 

wil pag gs | | Database Programming € Design 
gO Payment enclosed. Note: Subscription rate is tor LS delivery only. Canadian delivery: USi43.00. International delivery: P.O. Box 53481 


J Bill me. 


L1$§52.00 lor surface mail; L!Sé77.00 lor airmail, Please send payment with order in LS funds drawn ona 
a a ci 
LIS bank. Pease allow o=8 weeks for delivery, CA residents add $1.45 state tax. Boulder, CO 80329 O- 34051 


Winter 1993 





OS /2: The International Scene 


by Vicky Gallop 


EMEA DEVELOPER 
ASSISTANCE PROGRAM 


| EMEA DAP has expanded to provide 
marketing support to all its members in 
Europe, the Gulf countries, and Africa. 
Marketing support was announced to 
members in September, and was operating by 
early October 1992. Member response has been 
enthusiastic, with major developers such as 
Lotus and Borland International participating. 
Several new support programs are available: 


¢ OS/2 Award 

* 05/2 Compatibility Logos 

¢ OS/2 Application Product Publicity 
¢ OS/2 Joint Developer Events 

¢ OS/2 Customer References 

¢ OS/2 Solutions Book. 


Details of these programs are available on the 
DAP online network. Companies wishing to 
join the DAP should reach their country 
contact, listed on the following pages. 


EMEA DAP membership, recruited through 
these country contacts, totalled well over 1,000 
by the end of 1992 and is increasing rapidly. 


WORLDWIDE DAP 


Direct on-line technical support and other 
O$S/2 information is now available to 
developers around the world over 


International 


Compuserve. Log on to CompuServe and 
enter GOOS2DAP to enroll. 


VENDOR SUPPORT IN 
SWITZERLAND 


National developer support programs are 
growing in scope and activity. This issue, we 
focus on the ISV (independant software 
vendors) Support Program in Switzerland. All 
Swiss developers can participate in the 
program; they need only fill out a 


questionnaire. (Approval is given by Max yscky Gallop 
Merz; participation is restricted to vendors 

without other IBM contacts.) 

All participants have acess to ISV relation or nan te 
contact Max Merz, who can help with Log on to 
development questions about hardware, Compu Serve 
software, developing, customizing, and enter 


documentation, education, and contact with 

other IBM departments. Hardware and GOOS2DAP 
software announcements and information on } 34 
education and strategies are distributed to enroll in 
continuously. Members also have access to the DAP. 
twice-yearly ISV seminars with national and 

international speakers. 


DIAL IBM access is provided on request, as is 
authorization for solution associates, PS 
consultants, or remarketer sales points, if 
developers meet special conditions. In 
addition, the IBM customer support center 
facilities are available to independent vendors 
for customer seminars. 


Special Support Offering 
OS/2 application developers can buy complete 


systems (hardware and software) at a large 
discount. This offering is based on a contract in 
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OS/2 COUNTRY CONTACTS 

Australia Rohaini Cain 
Sydney 

Austria Georg Haschek 
Vienna 

Belgium Luc Gheysens 
Brussels 

Brazil Wagner Okutani de Sumare 
Almeida 

Canada Ken Faddelle 
Toronto 

Czechoslovakia Stepan Hradecny 

Crotia Zoran Kezman 

Denmark Poul Hansnes 
Copenhagen 

Egypt Shamel Abaza 
Cairo 

Finland Ilkka Ayravainen 
Helsinki 

France Jean-Paul Rambaud 
Paris 

Germany Hans-Michael Oest 
Stuttgart 

Greece Chryssina Hadjitheodorou 
Athens 

Gulf Countries Robert Kikano 
Bahrain 


Hong Kongand_ Roland Stranneborn 
Peoples’ Repub. of China 


Hungary Stevan Szarka 
China Roland Stranneborn 
Iceland Poul Hansnes 
(covered by Denmark) 
India Tang Wek Soon 
(covered by Singapore) 
Ireland Barry O’Brien 
Dublin 


OS/2 country contacts (continued on page 71) 
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61-2-354-7684 


43-222-21145 x2335 


32-2-025-3662 


55-192-65-7138 


1-416-946-3786 


422 7106111 
3041 624500 
45-45-93-4545 x4522 


20-2-349-2533 x269 


358-0-4594007 x4004 


33-1-48154660 


49-711-785-2417 


30-1-32-81111 


973-210880 


852-825-6996 


361 1654422 x108 


852-825-6996 


45-45-93-4545 


65-320-1181 


353-1-603744 x4629 


which the developer specifies the new 
program and the planned release date. 


OS/2 APPLICATIONS AROUND 
THE WORLD: SWEDEN 


ABB InfoSystems 


Sweden’s ABB Infosystems develops the 
SIGMA™ system integration manager, which 
integrates applications and application 
packages running in different computer 
environments, without any adaptations or 
changes in the applications. It became 
available in late 1992. 


ABB InfoSystems is a full-service information 
technology company with approximately 50 
employees. A member of the ABB Group, ABB 
InfoSystems has a turnover of approximately 
120 million SEK (Swedish Kronen). The 
company has products and services in several 
areas: information systems strategies, system 
development, and IS operations and systems 
management. 


The SIGMA Project 


The SIGMA project at ABB InfoSystems was 
spurred by customers’ need for integration 
between different computer environments 
such as the PS/2, AS/400™, and ES/390™ , 
IBM provided OS/2 support and network 
design for SIGMA, and ABB InfoSystems used 
IBM workstation technology including OS/2 
2.0, Extended Services, LAN Server, the 
Developer’s Toolkit, and the C SET/2 
compiler. 


Designed for companies that want to integrate 
standard packages, tools, and in-house 
applications, SIGMA allows users to approach 
corporate EDP systems (made up of 
independent subsystems) as one unified 
system. It can mix applications and tools 
running on different hardware and software 
platforms. 


With SIGMA, users can reach required systems 
through the menu or the icons available ona 
PC, bypassing the system’s menu and icons. A 
menu or icon selection can be created to 
perform a number of processes in one or 
several applications. SIGMA can also exchange 
information between applications and tools, 
restructuring data when necessary or 
performing a logging function for audit 
routines. A report-ordering function that 
creates ordered reports using different 
systems’ report generation functions (the agent 
technique or desired selection) can be ordered 
with only one menu selection. SIGMA can also 
review or reprint old reports, exchange a tool 
or an application, or create new information 
exchange links between subsystems. 


All the previous facilities are controlled by the 
SIGMA Engine™ software running under 
OS/2. The SIGMA Engine is the domain 
controller over all DOS- and LAN-based 
applications integrated through SIGMA. All 
workstations using SIGMA must be connected 
to the SIGMA Engine by an IBM LAN Server 
running Extended Services. 


SIGMA supports dialogues and applications 
operated from SIGMA workstations and 
manipulated in OS/2, PC DOS and MS DOS, 
or the IBM 5250 and 3270 terminals. 
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OS/2 COUNTRY CONTACTS 
Israel Arnan Dar 
Tel Aviv 
Italy Giuseppe Cigala 
Milan 
Indonesia Zakaria Ansori 
Jakarta 
Japan W. Kumada 
Tokyo 
Korea Bong Hun Park 
Seoul 
Malaysia Peter Lim 
Kuala 
Mexico Juan Carlos Fernandez Sarda 


Netherlands 
New Zealand 
Norway 
Pakistan 
Philippines 


Poland 


Portugal 


Romania 


Saudi Arabia 
Singapore 
South Africa 
Spain 


Slovenia 


Mexico 


Hans Langenhorst 
Amsterdam 


Rohaini Cain 
Sydney 


Kjell Tornby 
Oslo 


Inayat Ali Ebrahim 
Karachi 


Mike Valdes 
Manila 


Alexander Siatecki 


Jose Carlos Matos Alves 
Lisbon 


Constantin Florea 


Firas Halawani 
Jeddah 


Lisa Goh 
Singaopre 


Anita Volker 
Johannesburg 


Ignacio Martin Ibanez 
Madrid 
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972-3-697-8111 


39-2-5962.5178 


62-21-520-9500 


81-3-3808-4290 


82-2-781-6114 


60-37177788 


52-5-557-8588 x1846 


31-20-5653983 


61-2-354-7684 


47-2-99-93-83 


92-21-525181-190 


632-819-2000 x348 


482 6582991 
351-1-7955161 


401 614 3929 
966-2-6600007 


65-320-1181 | 


27-11-224-9111 


34-1-397-9231 


3061 441102 
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TO ORDER OS/2 DEVELOPER 
OUTSIDE THE U.S. 


| The OS/2 User Group 
Barton House 
Cirencester, Gloucestershire 
| GL7 2KE, U.K. 
Tel: (0285) 641 175 
Fax: (0285) 640 181 





‘RY CONTACTS 


Roger Labrell 46-8-793-1000 x1697 
Stockholm 










Switzerland Max Merz 41-1-207-3377 
Zurich 






Pontip Naruenartwanich 66-2-273-4267 
Bangkok 







Steve Kang 886-2-776-7530 


tna Cost is £40 U.K. for OS/2 User Group or 
Taipei 


DAP members, £50 UK for nonmembers, 

| plus £8 for postage and packing. The 
magazine can also be ordered through the 
OS/2 country contacts (see sidebar). 






Sevgi Gurbuz 90-1-280-0900 x1137 
Istanbul 







U.K. Nicola Colborne 44-256-343095 
Basingstoke | The OS/2 Applications Solutions Directory is 
also available for subscription outside the 
U.S. for £19.95 U.K. plus postage (£23 
airmail, £6.75 surface) and a £15 bank 
charge. The Directory may also be ordered 
through SLSS (IBM Doc. G362-0002). 






Worldwide Judy Osborne 1-407-982-4259 
Boca Raton DAP 
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Announcing TLIB 5.0! 
Version Control for DOS & OS/2 


e The experts loved TLIB 4: 
“amazingly fast... TLIB is a great system.” PC Tech Journal 


“TLIB has features and power to spare... TLIB is easy to use and 
the fastest of the reviewed packages.” Computer Language 
“T will not program without it.” Uptime Magazine 


NDP Fortran, C|C++ 
and Pascal Compilers 








* VMS, VS and MS extensions 






* Compatible with Framework and C Set 
— Fortran can call C Set or NDP C 






Uses IBM's Link386 to generate 
native OS/2 executables 





| Now TLIB 5.0 adds: 


Automatic branching. Automatic version labeling across branches. 
Language-independent preprocessor, for “conditional compilation” in 
languages which do not support it (like dBase). N-way-tree version 
numbers. Branch and whole-library locking. OS/2 support. 





* Can directly call the OS/2 APIs 







* Generate globally optimized 32-bit 
mainframe quality code 





-e Plus the features they loved in TLIB 4: 


Check-in/out locking. Branching, for paralle] development. Keywords. 
Full binary file support (does not depend upon CRs in the file like other 
products). Wildcard and list-of-file support; can create lists by scanning | 
source code for includes. Can merge (reconcile) multiple simultaneous | 
changes and undo intermediate revisions. Network and WORM optical 
disk support. Mainframe-compatible delta generator for Pansophic, 
ADR, IBM, Sperry formats. Includes integrated PD MAKE by L. Dyer; 
| also integrates with Opus™ MAKE, Slick” MAKE, others. 


Support for all coprocessors.and the i860 


* Available for DOS, OS/2, UNIX, NT 
and Coherent 










3rd party numerics and GUI Class 
libraries available 







MS-DOS $139, OS/2 (with MS-DOS) $195 + shipping. 
5 station network: MS-DOS $419, OS/2 $595. Call for other sizes. 


For more information, call our Tech Support Group 
at (508) 746-7341. 


M " Research Park 
icroWay P.O, Box 79 
Kingston, MA 02364 
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‘ The “OS/2 Accredited” logo signifies 
your expert status as a trainer, consultant 
» or system integrator of OS/2 2.X. Successful completion 
, of the OS/2 Accreditation Examination allows you to display the 

Vendors » logo on your marketing materials, stationery and business cards. 
A directory of Independent Mer \ To order the examination, remit $149.00 for each individual taking 
providing products and aa ve i the exam, in check or money order to: Skyline Consulting 
o support IBM OS/* | 


246 Wolcott Road,Suite 158, Wolcott, CT 06716 
| _ Or for more information call (203) 879-6486 


For information on products and services from OS/2 Independent 
Vendors, fax 914-766-3788 for a free directory. 


* Change Code Fast 
¢ Navigate Code Fast 


AMPLEVSL_FUNCT.APT | 
Link Macro Start Options Help 
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Learn Code Fast 


Sourcelink” 


SourceLink is an OS/2 programming development tool combining 
the speed and power of hyper-link source code access with a fully 
functional editor. The edit screens are context sensitive. Click to access 
on-line help. Click-click to access your source code. With over 100 
menu items to choose from, SourceLink is a feature rich programming 
environment. 
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() Case Sensitive 


i) Match leading characters 
M@ NOT Case Sensitive 


Double click on a function, symbol or other string. Let SourceLink “Tacskaphtips 

—r— Hultilypelndsex - “LINKER. ( 
LookupkkT ype — “LIWEER . { 
tilypelndex — “LINKER | 


pop up a list of occurrences. Double click on each occurrence and { 24) 
SourceLink will immediately display the source code. Use the integrated (26) 
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Unmatched in speed and convenience for finding and changing “LINK ° (1 Saath 

source code. Ideal for porting code, changing code, analyzing code, and 


creating programs from existing code, templates and samples. 
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SourceLink will save you valuable programming time and energy! 
SourceLink is a refreshing new experience in programming! 
Features: 
* HyperLink source code access. 
Fully functional editor. 
Supports 'C’, C++, MASM. 
REAX macro language interface. 
Presentation Manager GUI. 
WorkFrame/2 compatible. 
Generates function call tree displays. 


SourceLine Software, Inc. - 7770 Regents Rd #113-502 - San Diego, CA 92122 - (619) 587-4713 
Your Satisfaction is Guaranteed —__ 


* Spawn compiles and commands. 

* Create your own code templates. 

* Multiple windows. 

* Cross reference globals, symbols, 
dialogs, API calls, and more. 

Also available for OS/2 1.3. 

An OS/2 2,0 32 bit application. 


Context sensitive edit windows, 

Many file manipulation utilities. 

Find Files, Delete, Copy Files/ 
Directories. 

Context sensitive View Help. 

Multi-File/Dir. string search. 

Project configurable. 





World's most powerful tools for OS/2°® 


Srellele 


Hamilton C shell” 





The superior alternative to the 
standard OS/2 command proc- 
essor. Faithfully recreates and 
updates the entire UNIX®C shell 
language. Created explicitly for 
OS/2 using modern incremental 
compiler technology. Not one 
line ported from or created on 
anything but OS/2. Very high 
performance. Extensive support 
for multi-threading. 


Features: Full-screen command 
line editing * Filename and com- 
mand completion * History ¢ 
Arrow and function keys ® 
Unlimited size command lines « 
Recursive filename wildcarding 
® Fully nestable control struc- 
tures ®* Command substitution 
. * fees and shell procedures 

ATH i hashing * Background 
threads and processes, 


Hamilton Laboratories 
13 Old Farm Road, Wayland, MA 01778-3117 


Phone 508-358-5715 


Over 130 commands: alias, 
cat,chmod,cls,cp,cut,diff, 
dirs,dskrea oe dskwrite, du, 
eval, fqrep,qrep,hashstat 
head, hi istory, label phe, kite, 
Mmarkexe, more, Mv, popd, 
Irintf,ps, pushd, pwd, my, sed, 
sleep, split,strings, tabs, 
tail, tar, tee, time, touch, 
tr, unig vol, wait, wt 


whereis, xd and others. 


Meticulously adheres to OS/2 
conventions. Supports HPFS, 
long filenames and all networks 
under OS/2 1.2 or later and 32- 
bitand VDM applications under 
OS /2 2.0. 


$350.00. Unconditional 


satisfaction guarantee. 
($365 in Canada, $395 elsewhere.) 


FAX 508-358-1113 


CompuServe’ Access Software 


Get fast answers to your OS/2°® 
development and usage questions! 


Reduce the cost of communicating 
with IBM OS/2 technical support on 
the OS/2 Information Exchange! 


Use CompuServe intuitively with a 


multi-threaded OS/2 application! 


Creative Systems 


Programming Corporation 


Phone: (609) 234-1500 
Fax: (609) 234-1920 
Internet: 71511.151 @ compuserve.com 


$15 CompuServe usage credit Included 


CommDass 
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AlertVIEW: Network 
Management For Applications 
and Operating Systems 


by Shlomo Touboul 


This article shows how to use Shany's AlertVIEW™ 
API to send a SNA Generic Alert from any DOS, 
Windows, or OS/2 application to the IBM LAN 
Network Manager and NetView™, 


Alert VIEW was created by Shany and IBM to fill a 
gap in existing network management services. 
Although there are literally hundreds of 
management programs on the market, they are 
limited to the physical components of the 
network—hubs, cables, bridges, and so on. 


The most vital function of the LAN, the reason it 
exists, is to run applications and communications 
software. If users cannot supervise and monitor 
these programs, they run virtually without control. 


In a mainframe environment, application 
management is supplied by software systems such 
as NetView. With the proliferation of companies 
downsizing applications to LANs, most of this 
application management is lost. Alert VIEW, with 
its network management for applications and its 
Developer's Kit, is the first product to address this 
problem. 


ALERTVIEW 
he AlertVIEW product line enables users 


to monitor and supervise critical 
corporate applications from a single 
management console. 


The AlertVIEW workstation’s agent (AVS) is 
an “application sniffer” that looks into 
applications, locates the source of a problem, 
and sends SNA generic alerts to the IBM LAN 
Network Manager and IBM NetView. The 
AVS detects about 90% of application failures, 
which can be due to operating system errors, 


Tools 


network operating system failures, 
communication problems, hardware faults, 
and so on. The remaining 10% are application 
logic errors such as an application infinite 
loop. This can be reported with the Alert VIEW 
Developer's Kit. 


AlertVIEW Developer's Kit 


The AlertVIEW Developer’s Kit is an easy to 
use application program interface (API) for the 
creation and transmission of IBM SNA alerts 
from any DOS, Windows, or OS/2 application 
to the IBM LAN Manager, LAN Network 
Manager (LNM), or NetView console. It is 
shown in Figure 1. 


Figure 1: AlertVIEW Applications’ Agent and API 
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Using the SendAlert system call interface, a 
programmer may send application-generic 
alerts to the IBM focal point. Developers can 
use the AlertVIEW API to send application- 
critical logical errors such as “illegal login 
password,” “application out of resources,” or 
“abnormal application termination,” so 
applications can be continually supervised by 
NetView. This same API may be used for 
network management systems that are not 
compatible with IBM LAN Manager, LNM, or 
NetView. 


API CALLS 


From C: 


/* call to AlertVIEW API */ 

err_code=SEND_ALE (“Cannot write to file MYDATA.DAT, 
please call your LAN Admin” ); 

If (err_code) /* check error code */ print f (“AVAPI 
ERROR {d\n” ,err_code); /* print error message * / 


From Turbo Pascal: 


{ Call to AlertVIEW API } 

my_aps := ‘Cannot write to the file MYDATA.DAT, please 
call your LAN Admin’ ; 

err_code :=SEND_ALE (my_aps); { AVAPI system call } 

if err_code<>0 then { check error code } writein (‘AVAPI 
ERROR ‘,err_code); { print error message } 


From assembler: 


;AVAPI Parameters String 

my_aps DB “Cannot write to file MYDATA.DAT, please call 
your LAN Admin”, 0 

mov ax, SEG my_aps mov ds, ax ; APS segment mov dx, 
OFFSET my_aps ; APS offset mov ax, 1 ; function code int 
OfOh ; call AVAPI jc AVAPI_error ; jump if error 
AVAPT_error: 





Figure 2: API calls 


The API consists of a single input parameter 
made up of the AlertString and a call from any 
PC programming language to the SendAlert 
procedure. The API will perform all functions 
necessary to transform the text message to an 





IBM standard NMVT vector, and use the LLC 
802.2 communication to deliver the alert to the 
closest entry point. Developers don’t have to 
learn SNA formats, complex NMVT vector 
and sub-vector structures, or low-level 
network management protocols (LLC 802.2). 
With the AlertVIEW API, applications benefit 
from an alert service that until now was only 
available for mainframe applications. Because 
it supports additional network management 
protocols such as SNMP over IPX, Alert VIEW 
will support a multi- NMS protocol 
environment. 


Alert Control 


While you can use the AlertVIEW API by 
simply sending an alert string to the API 
system call, you can specify and control all the 
IBM code points (text indexes that are 
transformed to text on the IBM LAN Manager, 
LNM, or NetView console). If no code points 
are specified, the AlertVIEW API sets the 
default code point for software error, using 
special string characters in a way similar to the 
C printf() procedure. You may set up each 
code point to specify the alert’s probable cause, 
recommended action, user cause, and so on. 


AlertVIEW API Implementation 


For DOS workstations, the API run-time 
application is a DOS terminate-and-stay 
resident (TSR) program requiring 3K. The TSR 
extends the DOS services and supports the 
SendAlert system call using 80x86 interrupts 
similar to those of the DOS system calls. 


For MS-Windows workstations, the API run- 
time application is a Windows dynamic link 
library that can be called from any Windows 
3.0 or 3.1 application. The dynamic link library 
communicates with the DOS API TSR interface 
using the DPMI interface. 


For OS/2 workstations, the API run-time 
application is an OS/2 dynamic link library 
that can be called from any Presentation 
Manager or OS/2 text application. 


Using API from a command-line interface, a 
SENDALERT.EXE program for the DOS, 
Windows, and OS/2 platforms is also 
available to send alerts from the command-line 
interpreter or any batch file. 
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Supported Programming Languages task is to interact with any application running 

on the LAN station that needs to send alerts to e**s 
The Developer’s Kit includes a built-in support NetView to report user-defined alerts. ® 48 
library for the following programming eth 
languages: When the API calls take place, the AlertVIEW 

API module uses an internal interpreter that 
* PC ASM86_—_* Microsoft COBOL generates an NMVT vector from the 


programmer's alert string. The NMVT is 
transmitted over an 802.2 DLC interface or 
Novell IPX interface to the Alert VIEW Event 
Monitor, IBM LAN Manager, and IBM LAN 


« Turbo Pascal ¢ Microsoft PASCAL 


* Borland C Microsoft BASIC 


© Microsoft C 5.1 and 6.0 Network Manager. 

From the perspective of the entry points, there 
EXAMPLES FOR API CALLS is no difference between an alert generated by 

the AlertVIEW API (or by a user application) 
Examples of API calls from C, Turbo Pascal, and alerts generated by any other SNA 
and an assembler language are shown in components such as the 8230. 
Figure 2. 

ALERTVIEW PRODUCT LINE 
ALERTVIEW API OPERATION bgt 

The AlertVIEW Developer’s Kit is part of the 
The AlertVIEW API module may reside on product line. 


any LAN station, as shown in Figure 2. Its main 


Let Gpf write the GUI you design 
Using the powerful point and click visual programming environment of Gpf*, you can prototype, test 
and generate a complete OS/2 PM GUI in a few hours or days rather than the weeks or months 
required to hand code the same design. Even a relatively simple GU! can require writing thousands 
of lines of code, but with Gpf you simply draw your user interface on the screen. The integrated 
dialogue editor of Gpf permits actions and context sensitive help to be linked to controls as you 
create them. Gpf then generates error free ANS! C complete with embedded SQL statements. 

Gpf is optimized to take full advantage of OS/2 PM, the most powerful and robust GU! system 
available. Since Gpf code directly accesses the PM API, there is no run time module to distribute 
with your application and no added overhead or royalties. 

| Gpf keeps the entire design definition in one file. This permits easy re-entry for updates as well as 

| regeneration for different targets. 32 bit OS/2, 16 bit OS/2 and MS Windows code generation. 

















Gpf supports: 

« Simple and direct linkage of the interface to « Simple inclusion of bitmaps for use on About screens, 
program logic, built in or user defined functions. user-defined buttons, and menu or pulldown entries. 

« Direct association of help screens with controls, « Automatic embedded SQL statements to read OS/2 
and complete integration into the PM Help DataBase Manager tables, directly into combo or list 
Presentation Facility. boxes. 

* Flexible use of Presentation objects (fonts, * Multi-thread programming. 


colors, etc.) with controls and windows (client + Multiple source file generation. 
Se ae eel: » Automatic creation of controls that scale with window 
size. 


Try us out + Inclusion of user defined controls 

Order Gpf today for just $995.% 

Call Gpf Systems Inc. at: 

(203) 873-3300 or (800) 831-0017 - fax (203) 873-3302. Free demo software available 

30 Falls Rd., P.O. Box 414, Moodus, CT 06469 * GUI! Programming Facility 
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Corporate NMS 
Operation 


Figure 3: AlertVIEW Modules and IBM NetView 


Alert VIEW Station (AVS)—This workstation 
agent can be loaded on any network station. It 
detects DOS, Windows, and OS/2 application 
errors, system calls, BIOS, and network 
operating system errors, NetBIOS or IPX 
communication errors, and so on. 


AlertVIEW Manager (AVM)—This 
management console is used to remotely 
control the AlertVIEW agents, dynamically 
define alert filters, freeze and reboot 
workstations, and control application 
operations. 


AlertVIEW Event Monitor (AVEM)—This is an 
enhanced event monitor designed to collect, 
display, and automatically respond to all 
AlertVIEW and other IBM SNA alerts. 


Alert VIEW Anti-Virus (AVAV)—AVAV is an 

anti-virus agent used to detect, scan, remove, 
and alert the entry or focal point of a virus on 
any LAN station or server. 


TT | | 
NTL 
| oT | 


MN 
AAA 
: o 


NetView 


File Server Agent 
IBM LAN Manager 2.0 


AlertVIEW Agent 


AlertVIEW application 





API DEVELOPER’S KIT 
SPECIFICATIONS 


Hardware requirements—IBM PS/2 or PC or 
compatibles using PC-DO$S 3.3 or higher, 
Windows 3.x, OS/2 1.21, 1.3, or 2.0. 


LAN requirements—IBM Token Ring LAN 
supporting 802.2 interface or compatible or 
Novell Netware LAN running SPX/IPX. The 
alerts may be viewed on Shany’s AlertVIEW 
Event Monitor or IBM’s consoles. 


Focal point—IBM LAN Manager 2.0 or LAN 
Network Manager 1.0, LAN Network 
Manager 1.1 or any other IBM focal point. 


Memory requirements—The AlertVIEW API 
run-time application requires 5K of the 
workstation’s RAM. 


NetView support—Alerts may be forwarded to 
NetView by IBM LAN Manager 2.0 or LAN 
Network Manager 1.0 or 1.1. 
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Screen Capture & Conversion For 0S/2 
MORE FUNCTION, LESS PRICE....WHAT A CONCEPT! 
At One Up Corporation, abundance in function without abundance in price is 
paramount. Consequently, you'll find our screen capture application, Open 
Shutter, provides the flexibility you need to capture, modify, and output 
your desktop images at a price you'll want to photograph! 
as ftv YOUR IMAGES 
easy-to-use capture process allows you to select any rectangular 

area, window, or the entire desktop and capture with a single user- 
defined keystroke or mouse click. 
a last ae MADE SIMPLE 

tate your image at any angle, map your colors and modify your : 
color palette, and stretch or compress your image to aie ~ 
sion you need. Preview / compare multiple modified versions of 
your captured image prior to output. 
Soni ABOUT OUTPUT? 

den Shutter offers a varied selection of output devices includi 
printer and clipboard. For soft copy, save your image as an cond 
Windows BMP, ICO, or metafile. Also, save as an OS/2 pointer, a 
Windows cursor, or PCX, TIFF, GIF, PICT formats and more! 
So don't get discouraged by high price applications that don't deliver. For 
only $59.95 , Open Shutter offers you a cost conscious solution for your screen 
capture requirements. Ask us about our competitive upgrade price, too. 


O82 is a registered trademark of IBM Corporation 
Windows is a registered trademark of Microsoft Corporation 






|| Size: 92x62 Keys: move [1] 
Location: {168,337} 


One B.-1 a” 


1603 LBJ FREEWAY, SUITE 860 
DALLAS, TEXAS 75234 
1-800-678-01UP 
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PMfax: Device-Independent 
Fax Services for OS/2 2.0 


by Mark Ahlstrom and Bruce Keller 


The fax services described in this article make it 
easy to send fax documents from all applications 
that run on OS/2 2.0, The complexities of creating 
fax documents and dealing with fax hardware and 
protocols are encapsulated in PMfax™ (also 
distributed as FaxWorks™ OS/2), which allows 
applications to work with most PC fax hardware in 
stand-alone and LAN configurations. 


Fe machines are now installed in most 
business offices. Sending a fax document 
is almost as easy as dialing a telephone, and 
fax transmission provides immediate 
document delivery for the price of a phone 
call. For these reasons, fax transmission is 
increasingly becoming the method of choice 
for document delivery. 


When faxing a paper document between 
traditional fax machines, the sending fax 
machine scans the original document and 
transmits the scanned image over the 
telephone line using a standard fax 
transmission protocol, somewhat like the data 
transfer protocols used to transfer data files 
between computers. The receiving fax machine 
receives and prints the scanned image. 


A computer with a fax modem or fax 
coprocessor board can send and receive fax 
documents. Rather than scanning a paper 
document, fax software converts a document 
to a form suitable for fax transmission, without 
the blurring often produced by scanning. 
When used to receive, fax software can display 
a document on the computer screen or print it 
on a computer printer, using plain paper 
instead of the heat-sensitive paper often used 
in fax machines. Computer fax hardware is 
readily available, and many modems now 
include built-in fax capabilities. 


For a software developer, the implications of 
fax technology become obvious if you think of 
a fax machine as a printer connected by a 
telephone line. In other words, an application 
can print to millions of fax machines and 
computer fax devices throughout the world. 
The difficulty is that most applications don’t 
know how to deal with the intricacies of 
creating and sending fax documents. 


This article demonstrates the use of fax 
services that make it easy to create and send 
fax documents from applications. Just as OS/2 
printer drivers provide a device-independent 
way for applications to use printers, PMfax 
provides a device-independent way for 
applications to send fax documents with 
different types of fax modems and fax boards. 


PMFAX AND FAX SOFTWARE 


PMfax is an OS/2 fax software product 
consisting of an application program and a 
printer driver. 


The PMfax application, shown in Figure 1, is 
used to manage fax documents. With its 
viewing and editing features, the user can 
create documents using the Clipboard, text, 
bitmap, or PCX files, screen captures, other fax 
documents, keyboard input, and mouse-based 
drawing and editing tools. PMfax sends, 
receives, and prints documents using 
background threads. Supported fax hardware 
includes Class 1 and Class 2 fax modems, 
SatisFAXtion™ and Brooktrout™ boards. 
Using OS/2 time-critical threads, an optimized 
device driver for fax modems, and other OS/2- 
specific features, PMfax provides background 
fax operation. PMfax is available in stand- 
alone and LAN versions. The fax services 
described in this article can run on any OS/2 





machine, including LAN workstations and 
servers. 


Once the PMfax printer driver is installed, 
applications can create fax documents with 
their File/Print command. Documents can also 
be printed from WIN-OS/2 and DOS 
applications. The printer driver passes the fax 
documents to PMfax. When the printer driver 
has created a fax document, a pop-up window 
allows users to send it as is or save it for 
further editing. Multiple documents can be 
spooled for transmission. 


While most OS/2 services are provided 
through APIs, there are several advantages to 
using an OS/2 printer driver to create and 
send fax documents. With the OS/2 2.0 
Workplace Shell, the user can print by 
dragging a file object to a printer object. 
Because OS/2 printer drivers are a shared 
system resource, the printer device can be 
shared over a LAN and accessed by both OS/2 
and non-OS/2 workstations. In addition to 
making direct calls to the printer driver, 
applications can print to a printer driver by 
copying to a logical printer device such as LPT2. 
DOS and Windows applications can also print 
to the OS/2 printer driver this way. 


GENERAL FAX SERVICES 
ON OS/2 2.0 


When adding a fax interface to applications, it 
is best to support fax hardware from many 
vendors instead of a single product. It is, 
however, difficult to support even one type of 
hardware. Building fax capabilities into an 
application can be complex for several reasons. 
Many computer fax products are available, 
and there are several incompatible fax 
command language standards in common use. 
Also, fax data formats and protocols are 
relatively complex, and each page in a fax 
document must be created and compressed 
according to specific standards. Finally, on a 
multitasking operating system such as OS/2, 
fax services must be viewed as a shared 
resource that can be simultaneously used by 
multiple applications, even while sending and 
receiving occurrs in the background. 


For example, fax modems that use the Class 1 
fax command set are supposed to adhere to an 
international standard, but there are many 
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subtle differences between Class 1 fax 
modems. Although other fax modems are 
based on the Class 2 fax command set, this set 
was never approved as a standard; it is now 
being replaced by the incompatible Class 2.0 
standard. Coprocessor boards such as Intel's 
SatisFAXtion are even more challenging to use 
on OS/2 because they use proprietary fax I/O 
interfaces instead of COM ports. The situation 
is further complicated by variations in the 
many fax machines with which users must 
communicate. PMfax avoids much of this 
complexity with its hardware-independent 
interface. 


z 


a. Jee Outer 
3444 giwer Good 
GCastereilla, JPA O23B 
Ger tr. Suhr, 


a0 We Giacuseed, isbormecilen of —he Serle GE che Ger 
eoftearces progeen ie @t bebe). 


CT ap peatident Chat this weetvenre will satiety jeu 
repiuirmeats for Fan ood mks your office anre 
TL 


Bless call oe wits acy qoee-fooe. 


eimesrely, 


Mae & 


ack tome 


a ee 


John and Mike, 
Please check this out. 
Thanks, Joe 


=" 
I 
J 
i] 
1 
| 
| 
| 
| 
| 
| 
| 
i] 
| 
| 
! 
| 
i] 
| 
| 
i] 
| 
| 
i] 
i] 
i] 
| 
1] 
| 
| 
1 
| 
| 
1 
| 
| 
| 
| 
i] 
| 
i 
I 
i 
I 
I 
i 


Figure 1: PMfax application program 


FAX SPOOLING FOR 
TEXT OUTPUT 


When the PMfax printer driver is installed, its 
printer object is associated with a logical 
printer device such as LPT2. Thereafter, ASCII 
text copied to this logical device is 


automatically converted into a fax document. 81 
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OS/2 Adobe fonts are used to convert text 
characters into high-quality printed 
representations of the characters on the fax 
pages. 


ae 


>>T0= name, company, faxnumber Specifies recipient; multiple >>T0 
lines allowed 


>>FROM= name, company, Changes sender's cover sheet 
phonenumber, faxnumber information 


>>INFO= comment, heading, notes, | Changes header line and cover 
bitmap sheet items 


>>AT= time, date Specifies date and time for delayed 
fax transmission 


>>FONT= font, points, tabchars Selects any OS/2 Adobe font for 
text conversion 


>>PAGE= length, orientation Changes page length and 
landscape/ portrait orientation 


>>FILE= filename Stores fax as a TIFF-F file without 
making a fax log entry 







Table 1: Printer driver commands in PMfax 1.10 


>>FROM=Joe Sender, Joe’s Company Inc., 555-7788, 555-7766 
>>INFO=Comment text for cover page, Joe's Co. Inc., Test,* 
>>AT=5p, 3may92 

>>T0=Bill Smith, Smith Corp. ,555-5566 

>>T0="Jim “"JB”’” Brown”, Brown & Sons, 555-9999 
>>TO=Mark Jones, “Universal Fax, Inc.”, 1 (213) 555-1122 


This text will appear in the default font (Courier 12 point). 
>>FONT=,16 
Or you can make the current font bigger (this is Courier 16 point). 


>>FONT=Courier Bold Italic,18 

This text will be bigger, bolder and italic. You can have as many lines of 
text as you want. When the end of a page is reached, a new page is 
started. The default page length is a job property of the printer object, 
or can be changed on a page-by-page basis with the >>PAGE command. 


>>FONT=Helvetica 

This will be in Helvetica font, still in the 18 point size. 
>>FONT=Times New Roman, 90 

This is HUGE! 

>>FONT=*,* 

And back to the default font (Courier,12 point). 


Figure 2: Specifying special values for document elements 
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A user can create a fax document by using the 
COPY command to write a text file to the logical 
printer device. The printer driver will display 
a “Send Fax” window that specifies 
destination and cover sheet information and 
allows the user to send the document. Any 
OS/2, Windows, or DOS program or 
command file can also create a fax by copying 
text to the logical printer device. 


With PMfax, special printer driver command 
lines can be included in the text to 
automatically send the fax document to one or 
more recipients, as shown in Table 1. If any 
>>T0 command lines are included in the text, 
the “Send Fax” window is suppressed and no 
additional user action is required to transmit 
the document. Additional command lines can 
be used to specify special values for a 
document's font, page layout, cover page 
information and fax header line when they 
vary from the default, as shown in Figure 2. 


When the file in Figure 2 is copied to the 
device on which the printer driver is installed, 
a fax document is created and spooled for 
transmission to three recipients. An asterisk (+) 
parameter causes the default value to be used; 
font parameters can be omitted to leave a 
value unchanged. The user can set default 
cover sheet and header line strings in PMfax, 
and can adjust other transmission parameters 
such as how many times to retry if the 
recipient’s fax machine is busy. 


FAX SPOOLING FOR FONTS AND 
GRAPHICS 


Developers can directly spool fax documents 
by adding a few additional calls to the normal 
printing code. As demonstrated in Figure 3, 
even applications that use GPI calls for fonts 
and graphics can use PMfax’s printer driver 
commands. 


Fax creation and spooling can be integrated 
parts of an application: in addition to the 
File/Print command, the application can add a 
File/Fax command that creates and spools the 
fax document. Applications with print merge 
features that generate customized form letters 
can add a fax merge feature that will 
automatically fax the customized letter to each 
recipient. Applications do this by using >>T0= 
strings and other printer driver commands 
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vOID 
spool_fax( 

VOID ) 
{ 





HDC hdc; 

HPS hps; 

DEVOPENSTRUC dop; 

SIZEL sizl; 

PCHAR title = “MyFaxProg” ; 

PCHAR from = “>>FROM=Sam Sender,Sam’s Company, 555-1111,555-2222\r\n’ ; 
PCHAR to = “>>TO=Rick Receiver ,Rick Inc. ,555-3333\r\n" ; 

PCHAR info = “>>INFO=Please read this fax, Sam Co, ,Cover.bmp\r\n” ; 
POINTL ptl; 

LONG n; 

ULONG faxid; 


/* Fill in device open structure with selected printer information */ 
memset( &dop, 0, sizeof( DEVOPENSTRUC ) ); 

dop.pszLogAddress = printer_logname; 

dop.pszDriverName = printer_drvname; 

dop.pdriv = printer_drvdata; 

dop.pszDatalType = “PM_Q_RAW”; 

dop.pszComment = title; 


/* Open printer device context */ 
hdc = DevOpenDC( hab, OD_QUEVED, “*”, 
sizeof( dop ) / sizeof( PVOID ), (PDEVOPENDATA)&dop, NULL ); 


/* Open printer presentation space (if needed for Gpi calls)*/ 
sizl.cx = sizl.cy = 0; 
hps = GpiCreatePS( hab, hdc, &sizl, 
GPIF_DEFAULT | GPIT_NORMAL | GPIA_ASSOC | PU_LOENGLISH ); 


/* Signal start of document */ | 
DevEscape( hdc, DEVESC_STARTDOC, (LONG)strlen( title ), title, NULL, NULL ); ) 
DevEscape( hdc, DEVESC_RAWDATA, (LONG)strlen( from ), from, NULL, NULL ); 
DevEscape( hdc, DEVESC_RAWDATA, (LONG)strlen( to ), to, NULL, NULL ); 

DevEscape( hdc, DEVESC_RAWDATA, (LONG)strlen( info ), info, NULL, NULL ); 


/* Generate the document (with Gpi or more DevEscape raw text calls) +*/ 
ptl.x = 100; 
ptl.y = 100; 
GpiMove( hps, &ptl ); 
ptl.x = 700; 
ptl.y = 1000; 
GpiBox( hps, DPO_OUTLINE, &ptl, 50, 50 ); 
ptl.x = 200; 
ptl.y = 900; 
GpiCharStringAt( hps, &ptl, strlen( title ), title ); 


/* Signal end of document and get fax log id number */ 
n = sizeof( faxid ); 
DevEscape( hdc, DEVESC_ENDDOC, OL, NULL, &n, (PBYTE)&faxid ); 


/* Close printer */ 


GpidestroyPS( hps ); 
DevCloseDC( hdc ); 
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Figure 3: OS/2 printing to the PMfax printer driver with automatic spooling for transtitssion 
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before issuing the application’s standard 
printing commands, as shown in Figure 3. 


PLANNED EXTENSIONS 


Several additional features are planned for 
PMfax. Most developers prefer to approach fax 
services like printer services, allowing the fax 
application to manage fax delivery in the same 
way print spoolers manage printing. But in 
some cases developers need additional control. 
Functions will be added that allow 
applications to check the status of their fax 
jobs, schedule additional delivery attempts, 
and delete documents after transmission. 


The Keller Group plans to add printer driver 
commands for placing graphics files on the fax 
page and appending other fax document files. 
These commands will allow any application, 
including DOS applications and command 
files, to create complex fax documents. In 
addition, enhanced LAN versions of PMfax 
will soon be available, with versions that 
support simultaneous use of multiple fax lines 
in each fax server. 


SUMMARY 


Faxing has become common for document 
delivery, and many applications can benefit 
from transmitting data by fax. Through fax 
services, applications can operate 
transparently with most PC fax hardware 
products in stand-alone, LAN, and multiline 
configurations. 
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Bruce Keller, Keller Group Inc., 8600 Jewel 
Avenue North, Stillwater, Minn, 55082, (612) 
429-7273, fax (612) 653-1987. Keller is a founder 
and vice president of Keller Group Inc. He 
previously founded Airplan Systems (acquired by 
Continental Airlines), where he pioneered the use of 
OS/2 LANs for high-volume automatic fare- 
checking services. Previously, he worked for Cray 
Research, where he ported the UNIX kernel to the 
Cray-2 computer. He holds a B.A. in mathematics 
from St. Olaf College. 


Mark Ahlstrom, Keller Group Inc., 8600 Jewel 
Avenue North, Stillwater, Minn, 55082, (612) 
429-7273, fax (612) 653-1987. Ahlstrom is a 
founder and vice president of Keller Group Inc., 
which develops device drivers and APIs distributed 
by several fax manufacturers. Previously, Ahlstrom 
was a founder of Airplan Systems and a member of 
the artificial intelligence department at the 
Honeywell Computer Sciences Center. He holds a 
B.S. in biochemistry and an M.S. in biomedical 
engineering, both from the University of Wisconsin 
at Madison. 
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Why PL/I? 


by Davinder S. Athival 


Readers may be wondering what an article on PL/I 
is doing in a magazine devoted to OS/2. ISVs most 
likely use C and are reasonably happy with it, while 
corporate in-house progranimers may or may not 
have used PL/I in a mainframe environment. 

Either way, the idea of using PL/I on the desktop 
may seem strange at first. But before you skip 
ahead, look more closely at PL/I’s power and 
productivity, and its new 32-bit implementation for 
OS/2, PL/I Package/2. PL/T Package/2, introduced 
in September 1992, is the newest language product 
of the SAA AD/Cyecle family. A personal version, 
PL/I Workstation/2, became available in December 
1992. 


Developers familiar with PL/I may wish to skip to the 
heading “PL/I Package/2 and PL/T Workstation/2 
Products” on page 88. The following is an overview 
of PL/l's functions and strengths. 


PL/I OVERVIEW 
Pu: is a free-form high-productivity 


language with a variety of features that 
support scientific, engineering, commercial, 
and system programming tasks. It is designed 
to offer robustness, machine independence, 
structured programming constructs, powerful 
exception handling, dynamic storage, a wide 
variety of other data types and aggregates 
(arrays, structures, and unions), I/O 
capabilities, and many built-in functions. 


Free-Form Structure 
PL/I is completely free-form and has no 


reserved keywords; it determines the meaning 
of keywords by context. The programmer can 


Tools 





concentrate on program logic rather than 
worrying about word use. For example, in 
PL/I it is valid to declare a variable named 
AREA, despite the fact that AREA is used as a PL/I 
keyword. Because PL/I offers many defaults, 
developers need not be aware of all the 
language’s features to use it confidently. 


Machine Independence 





PL/I data types are hardware independent. 
For example, an integer is defined as having a 
base and a precision. Therefore, FIXED 
BINARY(12) declares a binary integer of 12 data 
bits and FIXED DECIMAL(31) declares a decimal 
integer of 31 decimal digits even if the machine 
does not support packed decimal data. All 
PL/I implementations support all language 
data types, even those the hardware cannot 
support directly; this makes for truly portable 
code. 


Davinder Allival 


Program Structure 


PL/I is a block-oriented language consisting of 
packages, procedures, begin blocks, and 
statements. Because PL/I allows you to control 
the scope, visibility, shareability, and lifetimes 
of variables, exceptional conditions, and 
procedures, you can produce highly modular, 
independently testable, and reusable code. 


Structured programming constructs 


Besides providing the basic constructs of most 
other languages, PL/I adds significant power, 
which allows program logic to be highly 
modular and well structured for greater 
reliability and easier development, 
maintenance, and extensibility. PL/I has 
extremely powerful case statements and 
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looping constructs that permit combinations of 
until, while, and repetition specifications. It 
also supports multiple specifications of these 
loops. 


Data Types 


A variety of data types can be represented and 
manipulated in PL/I, making the language 
appropriate for a range of applications. 
Arithmatic data may be real, complex, 
floating-point, fixed-point, signed, unsigned, 
binary, decimal, numeric, or editable picture 
data. String data may be varying, nonvarying, 
character, bit, graphic, run-time adjustable, or 
compile-time fixed length strings. Program 
control data also supports pointer and offset 
locators, adjustable or fixed size areas for 
grouping dynamic allocations, entry data 
(function pointers), and file, label, and format 
data. AREA data may be written out to the 
disk and read back at a later date, even if the 
allocated data within an AREA is a linked list. 


Declare 1 Year(1901:2100), 


5 Temperature, 
7 High decimal fixed(4,1), 
7 Low decimal fixed(4,1), 
5 Wind_velocity, 


7 High decimal fixed(3), 
7 Low decimal fixed(3), 
5 Precipitation, 
7 Total decimal fixed(3,1), 
7 Average decimal fixed(3,1), 
3 * char(0); 





Figure 1: Array of structures to hold weather data 


The variety of data types provided in PL/I 
allows developers to concentrate on the 
application logic instead of finding ways to 
circumvent deficiencies in the programming 
language. 


Data Arrays, Structures, and Unions 


In PL/I, data items can be either single data 
elements or data aggregates and can be 
referred to either collectively or individually. 
Data aggregates can be arrays, structures, 
unions, arrays of structures or unions, 





structures or unions of arrays, and so on. This 
flexibility provides a strong foundation for the 
description and manipulation of data. Figure 1 
shows how an array of structures used to hold 
meteorological data for each month of the 20th 
and the 21st centuries might be declared. In 
Figure 1, the weather data for July 1991 is 
contained in the element Year(1991,7) of the 
array of structures Year. Portions of this data 
can be referred to by Temperature(1991,7) or 
Year.Month.Precipitation(1991,7). The upper and 
lower bounds of an array can be negative, 
zero, or positive. PL/I does not force a lower 
bound of zero or one, which can contribute to 
the readability, reliability, and maintainability 
of a program. 


Data Manipulation 


Data may be easily manipulated as individual 
items or as an aggregate. A single invocation of 
the SQRT function, for example, can take the 
square root of an entire array, producing an 
identical array containing square root values in 
the corresponding elements. In other 
languages, in contrast, array and aggregate 
operations must be broken into elementary 
operations, which results in less 
understandable and less maintainable code. 


Built-in Functions 


PL/I provides almost 200 built-in functions, 
pseudovariables, and subroutines that 
manipulate scalar and aggregate data. These 
functions cover character, bit, and graphic string 
data, arithmetic computation, mathematical 
computation, floating point inquiries, floating 
point manipulation, integer manipulation, — 
precision handling, array manipulation, storage 
control, condition handling, input and output, 
and date and time manipulation. 


Restricted Expressions 


Restricted expressions are expressions, of any 
complexity, evaluated at compile time. Figure 
2 shows a static “hex to character” translate 
table. The compiler evaluates complex 
expressions involving these nested built-in 
functions during compilation. The code, 
entirely portable across platforms, is character 
set (ASCII vs. EBCDIC) and code page 
independent. This operation is much more 
complicated in other languages. 
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Storage Classes, Control, and Dynamic 
Storage Allocation 


PL/I offers four storage classes: AUTOMATIC, 
STATIC, CONTROLLED, and BASED. 
Application objects’ data type, representation, 
nature of use, and so on normally dictate the 
type of storage class used for each. With PL/I, 
programmers can dynamically allocate and free 
BASED and CONTROLLED storage. All data, 
not only static data, may be automatically 
initialized for all storage classes upon allocation. 
This leads to more readable and reliable code, as 
the initial values are part of the data declaration 
and are automatically assigned. 


Condition Handling 


PL/I can handle a variety of program 
execution problems. Problems can be detected 
by either the hardware (e.g., ZERODIVIDE), PL/I 
(e.g., CONVERSION), the operating system, or other 
software. These facilities allow you to detect 
exceptional conditions and take appropriate 
corrective action, as well as produce 
applications that provide non-stop operations. 
You can even handle user initiated attention 
interrupts and normal and abnormal program 
termination. 


Program Checkout 


There are several built-in program checkout 
conditions that automatically check a program 
for out of range array subscripts, strings, and 
substrings, as well as data that exceeds declared 
or machine supported precisions. These features 
help produce defect-free applications. 


Input and Output 


PL/I programs can process various sizes and 
types of records, access many different 

devices, edit and validate several types of input 
and output data, and produce report files. 
There are two types of input/output (I/O) in 
PL/I, record-oriented I/O and stream 1/O. 


Record-oriented I/O logically transmits one 
record at a time without performing any data 
conversion. These files may be stored in 
indexed, relative, or consecutive formats. 


Stream I/O deals with a logically continuous 
stream of characters (that may exist externally 
as physical records), transmitting one data item 


at a time while performing conversions 
between the internal and external forms. Data 
items may be transmitted as a list, edited list, 
annotated list, or a combination thereof. 
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While PL/I can handle mundane operations 
such as file opening and closing automatically, it 
offers programmers precise control over I/O 
operations, status, and exceptional conditions. 
1/O condition handling features include end of 
file reached, end of page reached, record not 
found, record truncated, I/O errors, file cannot 
be found, file open, key for which record was 





Figure 2: Use of restricted expressions in initialization of static data 


not found, source that caused conversion error, 
character within source that caused conversion 
error, file associated with the 1/O condition, 
number of current page, number of current line 
within a page, and bad data. Built-in functions 
help retrieve and change condition related data. 


Macro Facility 


PL/I's macro facility permits conditional 
compilation and modification of PL/I source 
code before compilation. For example, a 
programmer might include certain code during 
development and testing, and exclude it from a 
production program without reediting the 
original. Different parts of source code can also 


be platform-specific. 97 
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PL/I PACKAGE/2 AND PL/I 
WORKSTATION/2 PRODUCTS 


PL/I Package/2 and PL/I Workstation /2, 32-bit 
products for OS/2 2.0, have several new 
features that help developers write Presentation 
Manager (PM) applications using the SAA PL/I 
common programming interface and extensions 
that work with OS/2 2.0. These products also 
allow users to write non-Presentation Manager 
applications that can use built-in PM features to 
provide a graphical interface. The hardware and 
software required to run the products includes 
an IBM PS/2 or compatible machine with OS/2 
2.0 or later. 


PL/1I Workstation/2 provides all the features 
of PL/I Package/2, except VSAM-like record- 
level 1/O support and PL/I language levels of 
SAA and OS, Language level SAA2, of which 
SAA isa subset, is the only language level 
supported by PL/I Workstation/2 . 


PL/1 Package/2 and Workstation/2 also 
include facilities to enhance programmer 
productivity, program reliability, installation 
standardization, and control. They address 
numerous user requirements submitted by 
PL/I customers and SHARE and GUIDE 
groups in the U.S. and around the world, and 
implement most features from the American 
National Standard PL/I General Purpose 
Subset (ANSI X3.74-1987). 


The PL/I compiler produces high performance 
optimized object code that is reentrant and can 
be recursive. It meets the requirements of 
applications that exploit OS/2 and the 
Presentation Manager, and can help develop 
and maintain host applications. 


Programming Support 


Both PL/I products, consisting of the PL/I 
compiler and run-time libraries, fully support 
IBM WorkFrame/2. Several language 
extensions allow PL/I programs to 
communicate with programs written in other 
languages, including C Set/2. 


The PL/I products support the OPTLINK and 
the SYSTEM inter-procedure linkages, also 
used in C Set/2. In Figure 3, a PL/I program 
plays a tune using OS/2 services with no 





special coding required. It also shows use of 
named constants, such as whole, and restricted 
expressions in the initialization of the notes 
two-dimensional array. If one were to change 
the named constant whole, the compiler would 
automatically recalculate all dependent values 
and declarations. 


Figure 4 shows a PL/I program that converts 
hex strings to character. The object code 
produced by the compiler is as good as if it 
were hand-coded. 


Figure 5 shows a PL/I Presentation Manager 
program. No special coding is required; all 
communication with PM is direct. 


Hardware Support 


PL/I Package/2 and Workstation /2 exploit 
386™ and 486'™ processors including floating 
point hardware. Scaled and unscaled binary and 
decimal arithmetic are also fully supported. 


Programmer Productivity Features 


The following features significantly accelerate 
program development and maintenance and 
increase program reliability: 


e Features that detect or, in some cases, 
prevent the introduction of defects. Under a 
compiler option, for example, undeclared 
variables can be flagged as errors. 


Extensive use of ON-units, which allow 
sophisticated exception handling and 
recovery. A new condition, INVALIDOP, allows 
you to intercept and correct various IEEE 
floating point conditions. Another condition, 
STORAGE, lets you intercept out-of-storage 
situations. 


Clear and precise compile-time and run-time 
diagnostics, which pinpoint the original file 
and the line causing the problem. As one of 
the several improvements over $/370 OS 
PL/I, compiler listings show modified (as 
well as referenced and unreferenced) 
variables. 


Usability Features 


Several PL/I features allow you to tailor the 
products to your specific needs: 
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process; 
chimes: proc options(main reorder) ; 


dcl ( rest value( 0), 
g4  value( 392 ), 
c5 ~=—- value( 523 ), 
d5 value( 587 ), 
e5  value( 657 ), 
whole value( 800 ) ) fixed bin(31); 

dcl notes(19,2) static nonassignable fixed bin(31) 

init( e5, (whole/2), 

c5, (whole/2), 
d5, (whole/2), 
g4, (whole), 

rest, (whole/2), 
g4, (whole/2), 
d5, (whole/2), 
e5, (whole/2), 
c5, (whole), 

rest, (whole/2), 
e5, (whole/2), 
c5, (whole/2), 
d5, (whole/2), 
g4, (whole), 

rest, (whole/2), 
g4, (whole/2), 
d5, (whole/2), 
e5, (whole/2), 
c5, (whole) ); 

del i fixed bin(31); 





on 


dcl playnote entry( fixed bin(31), fixed bin(31) ) 
returns( fixed bin(31) optional ) 
external( “DOSBEEP’ ) 
options( byvalue LINKAGE(SYSTEM) ); 


dcl restnote entry( fixed bin(31) ) 
returns( fixed bin(31) optional ) 
ext( “DOSSLEEP’ ) 
options( byvalue LINKAGE(SYSTEM) ); 


do i = lbound(notes,1) to hbound(notes,1); 
if notes(i,i) “= 0 
then call playnote( notes(i,1), notes(i,2) ); 
else call restnote( notes(i,2) ); 


end; 
end; 


ac an ts Eo ore ‘ 
Figure 3: Program playing a tune 
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*process langlvl(saa2) or(“|*) not(‘~*) 
*process dft( byvalue reorder ) opt(2) 
*process prefix ( noFixedOverflow ) lLimits(extname(31)); 





eR 


hex2char: procedure(addr_out, length_in, addr_in); 
declare addr_out byvalue pointer; 
declare length_in byvalue fixed bin(15); 


declare addr_in byvalue pointer; 


declare 
1 * based, 
2 first_half unsigned fixed bin(8), 
2 next_half unsigned fixed bin(8); 


unsigned fixed bin(8) based; 
unsigned fixed bin(8); 
unsigned fixed bin(8); 

fixed binary(31) initial (0); 


declare based_bin8 
declare left_half 
declare right_half 
declare bytes 


/* note that this variable is static */ 
/* it is also code page independent +*/ 


del 
1 * union static nonassignable, 
2 cased_hex(0:255) fixed bin(8) unsigned, 
2 * bit( 8+#256 ) 
init( ( 
( copy (“ff’b4, 256) ) 
& ( copy (“ff “b4, index (collate(), “0’)-1) 
|| “00010203040506070809 *b4 
/ || copy(‘ffb4,256-(10+index(collate(),“0°)-1)) ) 
& 


copy (“ff “b4, index (collate(),’a*)-1) 
|| 


| 
& ( 
| 


—$ — « ———— 


“Oa0b0c0d0e0F *b4 


copy (“ff ’b4,256-(6+index(collate(),’a‘)-1)) ) 
copy (‘ff “b4, index (collate(),“A’)-1) 


“Oa0bOcOd0e0F *b4 


Is 


copy (‘ff ’b4,256-(6+index(collate(),“A“)-1)) ) 


do while( bytes < length_In ); 


left_Half 
= raise2( 
right_Half 


cased_hex( addr_in->first_half ), 4 ); 


= cased_hex( addr_in->next_half ); 


addr_out->based_bin8 
= ior( left_half, right_half ); 


addr_out = addr_out + 1; 


addr_in = addr_in + 2; 
bytes = bytes + 2; 


end; 
end; 
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*PROCESS LANGLVL( SAA2 ) INCLUDE(EXT (INC)) MACRO; 
*PROCESS LIMITS(EXTNAME(31)) AC F ) S F( W, 20); 
*PROCESS MARGINS (2,100) ; 





PM_App_Package: Package exports (PM_App); 
/* INCLUDE files +/ 


“NOPRINT; 

YOCL INCL_WIN CHAR; 
ZINCL_WIN = ‘Y’; 
YINCLUDE 0S2; 
“PRINT; 


PM_App: Proc options( main ); 

/* Constants */ 

dcl title char( 30 ) static init ( ‘PL/I Package/2 Demonstration’Z ); 

dcl flags fixed bin(31) static init(( FCF_TITLEBAR + FCF_SIZEBORDER + 
FCF_SYSMENU + FCF_MINMAX + FCF_SHELLPOSITION + FCF_TASKLIST + 
FCF_VERTSCROLL + FCF_HORZSCROLL )); 

/* Local variables +*/ 

dcl hwndClient HWND; 


dcl AnchorBlockHandle HAB; 
dcl MessageQueueHandle HMQ; 


dcl MessageQueue QMSG; 
dcl WindowHandle HWND; 
/* Code +*/ 


AnchorBlockHandle = WinInitialize( 0 ); 
MessageQueueHandle = WinCreateMsgQueue( AnchorBlockHandle, 0 ); 


Call WinRegisterClass 
| ( AnchorBlockHandle, 
addr( title ), 
PM_App_WinProc, 
CS_REDRAW, 
0); 


WindowHandle = WinCreateStdWindow( 
HWND_DESKTOP, 
WS_VISIBLE, 
addr( flags ), 
addr( title ), 
addr( title ), 
0, 
null(), 
0, 

addr( hwndClient )); : 
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do while ( WinGetMsg( AnchorBlockHandle, addr( MessageQueue ), 
null(), 0,0) “= 0); 
Call WinDispatchMsg( AnchorBlockHandle,addr( MessageQueue )); 
end; 





Call WinDestroyWindow ( WindowHandle ); 

Call WinDestroyMsgQueue( MessageQueueHandle ); 
Call WinTerminate( AnchorBlockHandle ); 

END; 


PM_App_WinProc: proc( WinHandle, msg, mpi, mp2) 
options(byvalue Linkage(system)) returns (MRESULT); 


/* Parameters */ 


Decl WinHandle HWND; 

Decl msg ULONG; 
Decl mpi MPARAM; 
Del mp2 MPARAM; 


/* Local Variables */ 


dcl rectangle RCL; 
dcl hps HPS; 
dcl hello char(12) static init (‘Hello World’); 


/* Code */ 


select (msg); 
when( WM_PAINT ) 

do; 
hps = WinBeginPaint(WinHandle, null(), null()); 
Call WinQueryWindowRect(WinHandle, addr(rectangle) ); 
Call WinDrawText(hps,12,addr (hello) ,addr(rectangle) ,0,0,DT); 
Call WinEndPaint(hps) ; 

end; 


when( WM_ERASEBACKGROUND ) 
return ( TRUE_PTR ); 


when( WM_BUTTONIDOWN ) 
do; 
Call WinSetActiveWindow( HWND_DESKTOP, WinHandle ); 
Call WinAlarm( HWND_DESKTOP, WA_NOTE ); 
display( ‘Button 1 is pressed’ ); 
return( TRUE_PTR ); 
return{ WinDefWindowProc( WinHandle, msg, mpi } }: 
end; 


Figure 5: A Presentation Manager program (continued on page 93) 
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when( WM_BUTTON2DOWN ) 
do; 
Call WinSetActiveWindow( HWND_DESKTOP, WinHandle ); 


/* sound a different tone */ 
Call Windlarm( HWND_DESKTOP, WA_ERROR ); 


display( ‘Button 2 is pressed’ ); 
return( TRUE_PTR ); 


return{ WinDefWindowProc( WinHandle, msg, mpi } }: 
end; 


otherwise 
return( WinDefWindowProc( WinHandle,msg,mp1,mp2 )); 
end; 
return( null() ); 
end; 
end PM_App_Package; 





Figure 5: A Presentation Manager program (continued from page 92) 


¢ Compiler options that can be specified in dynamic condition prefix enablement and 
environment variables, on the command disablement, language rules enforcement, 
line, or in the *PROCESS statement, compiler listings, and alternate code points 
for OR and NOT symbols. 


e File extensions, location and search 
tailorability for INCLUDE and macro processing = Input and Output Facilities 


¢ Ability to create dynamic link libraries. Edit-, list-, and data-directed stream I/O is 
supported for byte-stream and record files. In 
National Language Support (NLS) addition to record-level [/O support for byte- 


stream consecutive data sets, PL/I provides 
direct and sequential read, write, and update 
support for VSAM-like indexed, relative, and 
consecutive data sets. 


Both PL/I Package/2 and Workstation/2 are 
NLS enabled and provide national currency 
symbol support in picture data. Identifier 
names can use European alphabetic characters 


ise 


such as “Ui” or “Nn.” Printer destined files are also supported; they 
may be printed locally or remotely on a host 


Compile-time facilities system. 


There are many compile-time facilities in PL/I, 


The display statement is supported in 
including: 


Presentation Manager and non-Presentation 


* Control of the degree to which the compiler Manager environments. 


optimizes source code 


. ; THE FUTURE OF PL/I 
¢ Diagnostic message control, which permits 
specification of message limit and softening, —_ Future editions of PL/I will include support of 
strengthening, or suppression of messages SOL and CICS in native mode, SQL, IMS, and 
from the compiler CICS in host emulation mode, and object 


oriented language. 
¢ Control of language level enforcement, 


application of language related defaults, 
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Programming the OS/2 
Container Control: The Basics 


by Peter Haggar and Peter Brightbill 


The container control is shipped in OS/2 2.0 as a 
32-bit control and in the IBM CUA controls library 
(CCL/2) as a 16-bit control. The container is 


functionally equivalent in the two products, and the 


information in this article can be used by 
application develdpers working with either product. 
This article assumes Nie'reader has limited 
knowledge of the cantainer control or at least has 
read the information in the OS/2 2.0 
Programming Guide Volume II, Chapter 18. 
More information on the container control will 
follow in the next issue. 


The container control is large and complex. While 
this article is not intended to cover every aspect of 
the container, it provides information that can help 
developers write an application using it. 


STRUCTURE OF A 
CONTAINER APPLICATION 


[* container control was designed to be 
extremely flexible to satisfy the needs of 
most applications. There are several basic 
concerns when designing an application. First, 
applications need not expose all the container’s 
functions, such as drag and drop or the direct 
edit feature. To prohibit the editing of text in 
the container, set the CCS_READONLY style at 
creation. The container provides many views 
to display its data; the application can choose 
to support some or all of those views. 


Developers must also decide how to allocate 
and insert container records. For the purpose 
of optimization, records should be allocated 
and inserted in groups rather than 
individually. Grouping records reduces the 
time needed to allocate records and populate 


the container. You can allocate and insert n 
records with two WinSendMsg calls, as opposed 
to 2n WinSendMsg calls if you were to allocate 
and insert each separately. A good rule is to 
avoid any excessive WinSendMsg calls. This is 
especially important with 16-bit PMWIN in OS/2. 
In this setup, the 32-bit application calls 16-bit 
code in PMWIN, which in turn calls the 32-bit 
container control. On the return, the 32-bit 
container code returns to the 16-bit PMWIN code 
and then back to the 32-bit application code. 
Converting between 16- and 32-bit memory 
models, or “thunking,” can be costly in terms 
of clock cycles. 


STRUCTURES 
RECORDCORE and MINIRECORDCORE 


The container uses one of two structures to 
store record data, RECORDCORE and MINIRECORDCORE. 
The structure used depends on the style set by 
the application when a container window is 
created. (The CCS_MINIRECORDCORE style indicates 
that the container is to use MINITRECORDCORE.) 
MINIRECORDCORE, which minimizes application 
memory use, uses 28 bytes, or half the size of 
the RECORDCORE structure’s 56 bytes. But the 
ability to use less memory is rarely free; this 
situation is no exception. Certain functions are 
inoperable, or at least more complicated, with 
the MINIRECORDCORE structure. 


With MINIRECORDCORE, the tree name view cannot 
be used properly. The bitmaps and icons 
displayed in this view are stored in the 
TREEITEMDESC structure, which is pointed to by 
RECORDCORE. If you use the tree name view with 
MINIRECORDCORE, the same icon designates the 
expanded and collapsed icon. This can be 
confusing to the user. In addition, the 





MINIRECORDCORE is restricted to one text string 
pointer that displays text for each record in 
text, name, icon, and tree view. RECORDCORE, 
however, provides a separate text string 
pointer for each view. In MINIRECORDCORE, you 
cannot use bitmaps, as only one icon handle is 
provided (compared to two icon and two 
bitmap handles in RECORDCORE). 


Unlike RECORDCORE, MINIRECORDCORE does not 
provide a mini icon handle. To use mini icons 
with MINIRECORDCORE, provide a mini icon handle 
for the hptrIcon field of the MINIRECORDCORE 
structure. Set the s1Bitmap0rIcon field of the 
CNRINFO structure to specify icon size. This is 
necessary because the container is expecting a 
system default icon size. The container uses 
the system values SV_CXICON and SV_CYICON to 
determine the size of a default icon. If the 
given icon is a different size than that specified 
in the s1Bitmap0rIcon field, it will be stretched or 
compressed as needed. This technique is 
shown in Figure 1. 


After determining which of the two container 
record storage structures to use, you may want 
to store more information per record than is 
provided by either RECORDCORE or MINIRECORDCORE. 
Determine what information you wish to store 
for each record, then allocate the extra memory 
on the CM_ALLOCRECORD message. Applications 
that use the details view usually add more 
memory to each record to store information to 
be displayed in the columns. In an object- 
oriented environment in which the record 
represents an object, the instance data for the 
object can be added to the record. This is the 
technique used by the OS/2 2.0 Workplace 
Shell, which uses the container control for its 
folder object. 


If any additional data is to be added to each 
record, the application needs to typedef a 
structure as shown in Figure 2. 


MINIRECORDCORE or RECORDCORE must be the first 
field of the structure. This is important, as the 
container always returns pointers to RECORDCORE 
or MINIRECORDCORE. You can then typecast the 
pointer to, in this case, PRECORDOBJECT, and be 
able to address the container record and all 
additional data. In addition, when an 
application has to pass a pointer to a record for 
a particular message, it must point to either 
MINTRECORDCORE or RECORDCORE, as shown in Figure 3. 
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CNRINFO and CM_SETCNRINFO 


An internal CNRINFO structure describes most of 
the relevant information used by the container. 
To change the information in this structure, 
use the CM_SETCNRINFO message. The application 
should allocate its copy of the CNRINFO structure 
and set all fields that are to be changed. The 





/* Using the MINIRECORDCORE to display mini icons in the container. */ 
PMINIRECORDCORE pRecord; 
CNRINFO Cnrinfo; 


/* Specify a size for the mini icon. 
* a menu is commonly used. */ 

CnrInfo.slBitmapOrIcon.cx = WinQuerySysValue (HWND_DESKTOP, SV_CYMENU) ; 

CnrInfo.slBitmapOrIcon.cy = CnrInfo.slBitmapOrIcon.cx; 


The system value for the size of 


/* Tell the container to display all icons this size. */ 
WinSendMsg (hwndCnr, CM_SETCNRINFO, 
MPFROMP(&CnrInfo), MPFROMLONG(CMA_SLBITMAPORICON)) ; 


/* Assign the mini icon to the MINIRECORDCORE. Then insert the 
* record into the container. */ 
pRecord->hptrIcon = WinLoadPointer (HWND_DESKTOP, NULL, ID_MINIICON); 


WinSendMsg (hwndCor, CM_INSERTRECORD, 
MPFROMP(pRecord), MPFROMP(&RecordInsert) ); 


Figure 1: Mini icons with MINTRECORDCORE 


typedef struct _RECORDOBJECT 


MINIRECORDCORE MiniRec; 
ULONG ulCount; 
BOOL binit; 
SHORT sID; 
PSZ pszDept; 
CDATE Date; 

} RECORDOBJECT; 

typedef RECORDOBJECT *PRECORDOBJECT; 


<-- Be sure the MINIRECORDCORE or 
RECORDCORE is first. 


| Additional data. 


SS Se 


Figure 2: Application defined container item 


application should send the CM_SETCNRINFO 
message, setting the appropriate flags to 
indicate which fields are to be updated. The 
container will then copy the information to the 
internal CNRINFO structure it manages. 


IBM OS/2 Developer 


SSS SSS 











CM_QUERYCNRINFO can be used to retrieve a CNRINFO 
structure in use by the container. This message 
is necessary if your application needed 
information about the container stored in the 
structure. For example, to determine the 
container’s current view, use CM_QUERYCNRINFO and 
check the attributes in the flWindowAttr field. 


PRECORDOBJECT pRecObj; 
PRECORDOBJECT pRecParent; 
RECORDINSERT RecordInsert; 


/* Allocate a MINIRECORDCORE plus the additional bytes needed from the 
* RECORDOBJECT structure. *#/ 
pRecObj = (PRECORDOBJECT)WinSendMsg(hwndCnr, CM_ALLOCRECORD, 
MPFROMLONG(sizeof(RECORDOBJECT) - 
sizeof (MINIRECORDCORE)), 
MPFROMLONG(nRecords)) ; 


/* Assign the necessary data to the record. */ 
pRecObj->MiniRec.cb = sizeof (MINIRECORDCORE) ; 
pRecOb j->MiniRec.hptricon = hptrCarIcon; 
pRecOb j->ulCount = 1; 

pRecObj->bInit = TRUE; 

pRecObj->sID = 100; 

strcpy (pRecObj->pszDept, pszDeptTitle); 


RecordInsert.pRecordParent = (PRECORDCORE)pRecParent; 


/* Insert the record */ 
WinSendMsg (hwndCnr, CM_INSERTRECORD, 
MPFROMP(&pRecObj), MPFROMP(&RecordInsert)); 


Figure 3: Record allocation and insertion 


/* Fill in the fields of the CNRINFO structure that we want 
* to update +/ 

Corinfo.xVertSplitbar 

CorInfo.pFieldInfoLast 


= 100; 
= pFieldInfoLastLeft; 


CorInfo.pFieldInfoObject = pFieldInfo; 


/* Using the proper flags, tell the container to use this 
* new information #/ 
WinSendMsg (hwndCnr, CM_SETCNRINFO, MPFROMP(&CnrInfo), 
MPFROMLONG(CMA_XVERTSPLITBAR | CMA_PFIELDINFOLAST | 
CMA_PFIELDINFOOBJECT)) ; 





Figure 4; Updating CNRINFO 
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THE DETAILS ON DETAILS VIEW 


Details view is one of the more popular views, 
and is the only view that uses the FIELDINFO 
structure. It can be one of the more 
complicated views to program to. The details 
view is a table of rows and columns. Each row 
is represented by a RECORDCORE or MINIRECORDCORE 
structure, and each column by a FIELDINFO 
structure. Many container attributes apply to 
the entire details view, while others can be set 
specifically for each column. 


Fields from the CNRINFO structure that apply to 
the entire details view are xVertSpLitbar, 
pFieldInfoLast, and pFieldInfoOb ject. 
Respectively, they set the x position of the 
splitbar, the last column in the left split 
window, and the column to receive IN-USE 
(CRA_INUSE) emphasis. Each is optional, 
depending on the setup of the details view. If 
your application does not display a splitbar, 
the xVertSplitbar and pFieldInfoLast fields are 
not used. The pFieldInfo0b ject field, if not set 
specifically, will default to the first column in 
the left window or the first column in an 
unsplit details view. All these fields can be 
specified individually or as a group with the 
CM_SETCNRINFO message. Figure 4 shows how to 
set these fields with a single CM_SETCNRINFO 
message. 


Other attributes, the CFA_* attributes, apply 
only to a specific column in the details view. 
Some apply only to the titles and others to the 
data area of the column. Memory for the 
FIELDINFO structure is allocated with the 
CM_ALLOCDETAILFIELDINFO message. The flTitle 
and flData fields of FIELDINFO are used to set 
specific attributes for each column before they 
are inserted into the container with 
CM_INSERTDETAILFIELDINFO. Any attribute can be 
changed after the FIELDINF0s are inserted by 
sending the CM_INVALIDATEDETAILFIELDINFO 
message. 


To display column titles in details view, set the 
CA_DETAILSVIEWTITLES container attribute in the 
flWindowAttr field of the CNRINFO structure, then 
send the CM_SETCNRINFO message specifying 
CMA_FLWINDOWATTR. For example: 


Cnrinfo.flWindowAttr = CV_DETAIL | 
CA_DETAILSVIEWTITLES | 
CA_DRAWICON; 
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WinSendMsg (hwndCnr, CM_SETCNRINFO, 
MPFROMP(&CnrInfo), 
MPFROMLONG(CMA_FLWINDOWATTR)); 


When column titles are to be used in the 
details view, specify the type of data to appear 
in each column title. This is done through the 
flTitle field of the FIELDINFO structure. Only 
two types of data, first, icons or bitmaps and 
second, text strings, are allowed in the details 
view column titles. When CFA_BITMAPORICON is 
specified, the container assumes that the 
pTitleData field points to an icon or bitmap 
handle, depending on whether the CA_DRAWICON 
or CA_DRAWBITMAP attribute is specified. If the 
CFA_BITMAPORICON attribute is not specified, the 
container will assume that the pTitleData field 
points to a text string. 


Column data can be icons, bitmaps, text 
strings, dates, times, or numbers. These are 
specified by setting the flData field of the 
FIELDINFO structure to CFA_BITMAPORICON, 
CFA_STRING, CFA_DATE, CFA_TIME, or CFA_ULONG, 
respectively. When one of these attributes is 
specified, the container assumes that the same 
type of data is contained at the location 
specified by the FIELDINF0’s offstruct field, as in 
Figure 5, 


Other options specific to the flData field are: 


© CFA_HORZSEPARATOR—Draws a horizontal line 
between the column title and the column 
data. 


© CFA_SEPARATOR—Draws a vertical line after a 
column; the line extends through the title 
area. 


* CFA_OWNER—Allows the application to 
ownerdraw a column. 


e CFA_INVISIBLE—Makes a column invisble. 


© CFA_FIREADONLY—Makes a column’s data, but 
not its title, read-only. To make a column 
title read-only, specify CFA_FITITLEREADONLY in 
the flTitle field. 


Data in a column can be aligned in any of nine 
different ways using CFA_TOP, CFA_BOTTOM, and 
CFA_VCENTER for vertical positioning and 
CFA_LEFT, CFA_RIGHT, and CFA_CENTER for horizontal 
positioning. These can be set differently for 
title and data in one column. 


The most important field in the FIELDINFO 
structure is offstruct, which tells the column at 
what offset from the begining of RECORDCORE or 
MINTRECORDCORE to find its data. All data 
displayed in details view is contained in or 
after RECORDCORE or MINIRECORDCORE. If any data is 
to be contained after, allocate record memory 
as shown in Figure 3. Figure 5 shows how 
FIELDINFO structures could be set up to display 





PFIELDINFO pFieldInfo; 


if (pFieldInfo = WinSendMsg (hwndCnr, CM_ALLOCDETAILFIELDINFO, 
MPFROMSHORT(numColumns), NULL)) 
{ 
/* First column title will be a string, and the data will be 
+ an icon */ 
strcpy (pFieldInfo->pTitleData, pszFirstColTitle); 
pFieldInfo->flData = CFA_BITMAPORICON; 
pFieldInfo->offstruct = FIELDOFFSET(RECORDOBJECT, MiniRec.hptrIcon) ; 


pFieldInfo = pFieldInfo->pNextFieldInfo; 


/* Second column title will be a string, and the data will be 
* the name */ 
strcpy (pFieldInfo->pTitleData, pszSecondColTitle) ; 
pFieldInfo->flData = CFA_STRING; 
pFieldInfo->offstruct = FIELDOFFSET(RECORDOBJECT, MiniRec.pszIcon) ; 


pFieldInfo = pFieldInfo->pNextFieldInfo; 


/* Third column title will be an icon of a calendar, and the data 
* will be the date +/ 

pFieldInfo->flTitle = CFA_BITMAPORICON; 

pFieldInfo->plitleData = hptrCalendar; 

pFieldInfo->flData = CFA_DATE; 

pFieldInfo->offstruct = FIELDOFFSET(RECORDOBJECT, Date); 





Figure 5; Setting up FIELDINFO 


different columns of data with the RECORDOBJECT 
structure defined earlier. Be sure that if any 
column contains string data, the 
corresponding FIELDINFO’s offstruct parameter 
must refer to a PSZ (pointer to a character 
string), not a character string itself. 
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TREE VIEW 


The tree view is used when the objects of a 
container are best represented in a hierarchy. 
The drives folder of OS/2 2.0, where a drive's 
directory structure is displayed, is an example 
of where a tree view is useful. In all, the 
container offers three different types of tree 
views: tree-text, tree-icon, and tree-name. 


The layout of the tree view is flexible and can 
be tailored to an application. The lines that 
connect child records to their parents can be 
specified as to their thickness and indentation 
depth. These values are set with the cxTreeLine 
and cxTreeIndent fields of the CNRINFO structure, 
respectively. This example shows how to 
display longer and thicker lines than those 
provided by default: 


Cnrinfo.cxTreeLine = 5; 

Cnrinfo.cxTreeIndent = 50; 

WinSendMsg (hwndCnr, CM_SETCNRINFO, &CnrInfo, 
CMA_CXTREELINE | CMA_CXTREEINDENT) ; 


The tree-icon and tree-text views use an icon to 
display the state (expanded or collapsed) of a 
parent record. The container provides default 
expanded and collapsed icons, which can be 
replaced with the hptrExpanded and 
hptrCoLlapsed fields of the CNRINFO structure. As 
with all icons used by the container, these can 
be sized. The following code sample makes the 
expanded and collapsed icons larger than the 
default size. 


1 


Cnrinfo.slTreeBitmapOrIcon.cx = 100; 

Cnrinfo.slTlreeBitmap0ricon.cy = 100; 

WinSendMsg (hwndCnr, CM_SETCNRINFO, &Cnrinfo, 
CMA_SLTREEBITMAPORICON) ; 


The tree-name view can be used to preserve 
screen real estate. In this view, the record's 
expanded and collapsed icon are two separate 
icons. The container displays the appropriate 
icon based on the state of a parent record. In 
this case, the application should utilize the 
TREEITEMDESC structure. Because the 
MINIRECORDCORE structure does not contain a 
PTREEITEMDESC field, the TREEITEMDESC structure 
and tree-name view should be used only with 
the RECORDCORE structure. For all records, the 
appropriate icons should be loaded into the 
TREEITEMDESC structures hptrExpanded and 
hptrCollapsed fields. This code sample loads 


icons to be displayed in tree-name view for a 
parent record. 


pRecord->pTreeltemDesc = malloc( 
sizeof (TREEITEMDESC) ); 

pRecord->pTreeltemDesc->hptrExpanded 
WinLoadPointer(...); 

pRecord->pTreeltemDesc->hptrCollapsed 
WinLoadPointer(...); 


To insert records in tree view, the RECORDINSERT 
structure needs to be set up properly. To insert 
records at the root level (items with no 
parents), the pRecordParent field should always 
be set to NULL. There are two options when 
inserting child records. If inserting the first or 
last (CMA_FIRST or CMA_END) child, the 
pRecordParent field must point to the 
appropriate parent record. When inserting 
child records that are not first or last, the 
pRecord0rder field must point to the previous 
child record and the pRecordParent field should 
be set to NULL. 


Although the container’s tree view is flexible, 
there are some limitations. Regardless of the 
selection model (extended, multiple, or single) 
chosen, the tree view is always single selection. 
Only the root-level items may be shown in the 
other container views. To show child records 
in other views, you could use record sharing to 
share these records with another container. 
While we have mentioned icons in this section, 
the container offers the same flexibility for 
bitmaps when the CA_DRAWBITMAP attribute is set. 


QUERY MESSAGES AND 
COORDINATE SYSTEMS 


There are a number of query messages 
provided by the container that allow you to 
query useful information. CM_QUERYVIEWPORTRECT, 
CM_QUERYRECORDRECT, and CM_QUERYRECORDFROMRECT 
are query messages that deal with coordinate 
systems. 


CM_QUERYVIEWPORTRECT deals with the workspace 
coordinates and container window 
coordinates, while the others work only in 
window coordinates. The workspace is 
defined by the extreme positions of the visible 
records and the workspace coordinate system 
is stationary. The container window viewport 
(the viewable section of the container’s 
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workspace) contains a subset of the entire 
workspace that is moved as the container is 
scrolled. The viewport does not include scroll 
bars and titles that may be present in the 
container window. CM_QUERYVIEWPORTRECT can 
retrieve the viewport’s size and position 
relative to the workspace (CMA_WORKSPACE) or 
relative to the container window (CMA_WINDOW). If 
only the size of the viewport is desired, either 
coordinate system can be used. 


CM_QUERYRECORDRECT is used to query a record's 
position relative to the container window’s 
origin. This value is dependent on the 
viewport’s current location and changes when 
the container is scrolled. The position of the 
record in workspace coordinates can be 
queried with CM_QUERYRECORDINFO. The record's 
workspace position does not change when the 
container is scrolled. 


It may be useful to determine which records 
intersect a given rectangle whose coordinates 
are relative to the container window origin, for 
example, if you wanted to know which record 
was under the mouse. With the mouse 
coordinates expressed as a rectangle, use 
CM_QUERYRECORDFROMRECT to search for the record 
under the mouse, if one exists. This code 
sample can be used in any view to retrieve a 
record under the mouse: 


QueryRecordFromRect.cb = 
sizeof (QUERYRECFROMRECT) ; 
QueryRecordFromRect.rect.xLeft = MousePt.x; 
QueryRecordFromRect.rect.xRight = MousePt.x; 
QueryRecordFromRect.rect.yTop § = MousePt.y; 
QueryRecordFromRect.rect.yBottom = MousePt.y; 
QueryRecordFromRect.rect.fsSearch = CMA_PARTIAL 
| CMA_ITEMORDER; 
pRecord = WinSendMsg (hwndCnr, 
CM_QUERYRECORDFROMRECT, 
MPFROMP(CMA_FIRST) , 
&QueryRecordFromRect) ; 


You may want to use the CMA_ZORDER flag in the 
fsSearch field if the container is ina 
nonautopositioned icon view (one in which 
the CCS_AUTOPOSITION is not set upon container 
creation). In this case, records may be 
positioned on top of one another. 





CLOSING A CONTAINER 
APPLICATION 


When your application is closed, it is 
responsible for freeing all memory, such as 
memory allocated for text strings used in 
records and columns. All icons and bitmaps 
loaded should also be released. 
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Implementing a Wastebasket 
In the Workplace Shell 


by David ]. Hock 


OS/2 2.0's shredder device is useful for 
permanently deleting items. To use the shredder, 
the user drags files or other items that are no longer 
wanted to the shredder icon on the desktop, and the 
item is instantly discarded. The main shortcoming 
of the shredder is that a shred operation is not very 
forgiving. In contrast, the wastebasket is a delete 
device from which users can recover previously 
discarded items . 


With the wastebasket, unwanted items are dragged 
to an icon on the desktop. Later, you can open the 
wastebasket and retrieve items placed there. When 
you are ready to permanently discard its contents, 
empty the wastebasket using a pop-up menu. You 
can also select an auto-empty feature so the 
wastebasket is automatically emptied each time you 
start your system. 


[Te wastebasket device, shown in Figure 1, 
can be easily added to the OS/2 2.0 
Workplace Shell, using existing object-oriented 
code as a model. This article explains the 
general object-oriented programming 
principles that are used to create a new object 
such as the wastebasket. It then describes how 
the wastebasket device was implemented in 
the OS/2 2.0 Workplace Shell. 


THE WORKPLACE SHELL AND 
OBJECT-ORIENTED 
PROGRAMMING 


Although the OS/2 2.0 Workplace Shell was 
developed in C, the System Object Model 
(SOM) environment allowed the Workplace 
Shell to support object-oriented programming, 
which uses objects consisting of data and 
functions that operate on that data. This 


grouping of data and function is known as 
encapsulation. Encapsulation is an excellent 
technique for hiding data and protecting it 
from accidental corruption. Together, the 
function and the values of the data define the 
behaviors of an object. 


An object can be thought of as a group of 
characteristics or an object class. An object 
class has one parent and many children that 
adopt behaviors from their parent object. 
Programmers can create new object types by 
creating descendant object classes (subclasses), 
reusing all parent behaviors needed for the 
new object class, and then modifying any 
behaviors that do not fulfill the requirements 
of the new object class. New behaviors can also 
be added to the new object class. 


A new object class can be very similar to its 
parent or it can be radically different, with 
little reuse of the parent behaviors. Since a 
very different child class requires extensive 
modifications to the new object class, it is 
desirable to choose a parent class that has as 
much as possible in common with the required 
object class. 


Applying Object-Oriented Programming to 
the Wastebasket 


To create a wastebasket, we need to find a 
similar object to use as a parent class. At first, a 
shredder seems the most likely candidate; both 
devices are used to delete items. But a 
shredder does not allow you to view its 
contents or remove items. In fact, a shredder 
exhibits no containment behavior at all. A 
folder, however, exhibits many behaviors 
needed in a wastebasket. You can drop items 
on a folder icon and view and remove its 
contents. Since a folder is behaviorally closest 


Winter 19953 





to a wastebasket, it was selected as a parent 
class for the wastebasket. 


To implement the wastebasket, you must 
modify some behaviors of the folder class. A 
“cannot drop” icon should be displayed if 
undeletable items are dragged over the 
wastebasket. The wastebasket icon and default 
title differ from those of a folder; as the 
wastebasket should not be copied, it should 
not have a Copy command in its pop-up menu. 
Instead, add an Empty now command to the 
menu and an auto-empty page to the settings 
view notebook. Also remove the Include page 
from the notebook, so users cannot hide the 
wastebasket contents. 


USING THE FOLDER TO 
IMPLEMENT THE WASTEBASKET 


Using an existing object class to create a new 
object class is known as “subclassing.” Once an 
object class is subclassed, existing behaviors 
are modified and new ones are added by 
writing C functions called “methods.” 


Each class has an associated abstract class 
object, the factory object, that creates instances 
of a class. The methods of a class object, or 
class methods, are defined along with instance 
methods when defining a class. 


Class methods operate on the class as a whole, 
allowing memory and methods to be 
efficiently shared by an entire class of objects. 
Icons, for example, are bitmap images that 
require a fair amount of memory. Storing an 
icon with its class rather than with each 
instance or occurence of an object saves 
memory. 


You can also save time by running a class 
method once for the entire class rather than for 
each instance of a class. Similarly, the code that 
loads an icon into memory is run only once 
during intialization of the class. 

In Figure 2, subclassing is done by creating a 
class definition file for the wastebasket. This 


file consists of several parts that define the 
object and its methods: 


® Class definition 


* Parent definition 


Figure 1: The wastebasket 


* Passthrough data 
¢ New methods 


* Modified or overridden methods 





The class definition specifies the name of the 
object class, its version number, and the prefix 
to be used for method names. The parent 
definition specifies the parent for the 
wastebasket class. In this case, WPFolder, the 
folder class, will pass on its behaviors and 
methods to the wastebasket class. 








The passthrough section passes C definitions 
through to the include file, where they will be 
interpreted by the C compiler. In this example, 
the constant IDKEY_AUTOEMPTY is defined as an 
index for saving and retrieving the value of the 
object data. 


Instance data, or object occurrence data, 
defines the state of an object. In this example, 
the instance data is very simple. A Boolean 
variable is declared to store the auto-empty 
flag. If the flag is set to true, the wastebasket 
will be emptied at system startup. 


Methods usually have similar parameters; the 
first parameter is a pointer used to reference 
the object instance and call other methods from 
within the method. 
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For direct access to instance data, call the 


GetData method at the beginning of a method. 


The method name will have a prefix that 


corresponds to its class, as in WPWastBGetData. It 


# WASTEBSK.CSC by Dave Hock 


# Include the class definition file for the parent class 


include <wpfolder.sc> 
# Define the new class 
class: WPWastB, 
file stem = wastebsk, 
external prefix = wpwstb_, 
class prefix = wpwstbcls_, 
major version = 1, 
minor version = 1, 
local; 
# Specify the parent class 
parent: WPFolder; 
# Specify the release order of new methods 
release order:SetAutoEmptyFlag, QueryAutoEmptyFlag; 
# passthru to C compiler 
passthru: C.ih; 
#define IDKEY_AUTOEMPTY 9000 
endpassthru; 
# Define instance data for the class 
data: 
BOOL bAutoEmpty; 
4 
# Define new methods 
methods: 
BOOL QueryAutoEmptyFlag(), private; 
BOOL SetAutoEmptyFlag(BOOL bAutoEmpty), private; 
# Specify methods being overridden 
override wpInitData; 
override wpModifyPopupMenu; 
override woMenultemSelected; 
override wpSetup; 
override wpSaveState; 
override wpRestoreState; 
override woQueryStyle; 
override wpDragQver; 
override wpAddFolderIncludePage; 
override wpAddSettingsPages ; 
override wpclsQueryTitle, classmethod; 
override woclsInitData, classmethod; 
override wpclsQueryIcon, classmethod; 
override woclsUnInitData, classmethod; 





Figure 2: The class definition file Wastebsk .CSC 


is better to access instance data by calling 
access methods, rather than referencing the 
variable directly. This allows the programmer 
to subclass an object and override the instance 
data access methods. Data access methods 
must, however, directly access the data being 
managed. In our example, two new methods 
that access the instance data item for the auto- 
empty flag are declared for the wastebasket 
object: QueryAutoEmptyFlag and SetAutoEmptyFlag. 


Finally, declare any existing folder methods 
that will be modified or overridden for the 
wastebasket. These methods dictate how 
folder behavior will be modified to create the 
wastebasket. The code for the wastebasket 
methods is contained in the .C file. 


OVERRIDING FOLDER 
BEHAVIORS 


Most of the creation of the wastebasket 
consists of overridding parent methods, both 
class and instance. 


When overriding a parent method, it is 
important that the parent method and 
functions be called within the new method, or 
important behaviors may be lost. Parent 
methods are called with a parent_ method 
prefix. For example, even though custom code 
is executed in the WpMenuItemSelected when a 
user selects “Empty now” in the pop-up menu, 
the parent method for menu selection must 
still be called to allow existing folder menu 
items to function. 


The following wastebasket class methods are 
overridden in C to create the desired 
behaviors: 


* wpclsInitData—This method is run once 
during a class initialization to initialize any 
data required for the class as a whole. With the 
wastebasket, it is used to load the device’s 
resource data and icons into memory from the 
resource file, as in Figure 4. 


® wpclsUnInitData—This method is run when a 
class is destroyed. It destroys a previously 
loaded icon, freeing some memory. The 
resource module is also released from 
memory. 
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[RARRAEREAAEA AAA AAK EAA ER AREA ERE AEE KARE EERE EERE SERA REAR A AAA ARK EAE ER ERE 


* METHOD: wpclsQueryTitle 

+ PURPOSE: This class method returns the default folder title for any instance 

+ of the password protected folder class.This title is used if a title is 

* not supplied in the WinCreateQbject() call. 

* INVOKED: By the Workplace Shell, upon instantiation of the object. 

FEE CGE E CCH AC GCA EOE ERE E / 
SOM_Scope PSZ SOMLINK wpwstbcls_wpclsQueryTitle(M_WPWastB *somSelf) { 

return(“Waste Basket); /* Return default title */ 

} 


[SERRE SSS OGRA AAA 
* METHOD: wpclsInitData 
* PURPOSE: This class method allows the initialization of any class data 


+ items. The overridden method simply obtains a module handle 
* to be used when accessing Presentation Manager resources, then 
* invokes the parent’s default processing. 


* INVOKED: By the Workplace Shell, upon loading the class DLL. 
FESO CIARA ERIE EEE III AA AAR AE DART RAE / 
SOM_Scope void SOMLINK wpwstbcls_wpclsInitData(M_WPWastB *somSelf) { 

CHAR ErrorBuffer([100] ; 


DosLoadModule((PSZ) ErrorBuffer, /* Obtain DLL module handle*/ 
| sizeof (ErrorBuffer), 
“WASTEBSK” , /* Module name */ 
&hmodThisClass) ; /* Module handle +/ 
hIcon=WinLoadPointer (HWND_DESKTOP, /* Load icons */ 


hmodThisClass, ID_WASTEICO) ; 
parent_wpclsInitData(somSelf) ; 
} 


[SAR AAAA AREA AA AAAS RAAT AAA A AER RA TRAE IR EERE ER RAE EIA A AAA TARA BH 
| * METHOD: wpclsQueryIcon 
* PURPOSE: This class method returns the handle to the default icon for 
* the class. Allows setting of the icon to a wastebasket. 
* INVOKED: By the Workplace Shell, upon instantiation of the object. 
JSG aa SESSA gO ERR EE EE EEE / 
SOM_Scope HPOINTER SOMLINK wpwstbcls_wpclsQueryIcon(M_WPWastB *somSelf) 
{ return (hIcon); } 
Gea aC Ga i Ee Ee 
* METHOD: wpclsUnInitData 
* PURPOSE: This class method allows the release of any class data items 
+ or resources. The overridden method releases the module handle 
+ obtained by wpclsInitData, then invokes the parent’s method. 
* INVOKED: By the Workplace Shell, upon unloading the class DLL. 
Jes a aa GH gga aa a Re / 
SOM_Scope void SOMLINK wowstbcls_wpclsUnInitData(M_WPWastB *somSelf) { 
WinDestroyPointer(hIcon) ; 
DosFreeModule(hmodThisClass) ; /* Free module handle*/ 
parent_wpclsUnInitData(somSelf) ; 


Figure 3: Class method implementations 
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both class and 
instance. 


* wpclsQueryTitle—This method is called by the 
Workplace Shell to query the default title for 
an object class. Overriding this method gives the 
wastebasket a default title other than “Folder.” 


* wpclsQueryIcon—This method is called by the 
Workplace Shell to query an icon used for a 
class of objects. Overriding this method 
replaces the folder icon with a custom 
wastebasket icon. 


Many instance methods are overridden to 
implant the wastebasket’s behavior. If these 
methods are intercepted, the management of 
the auto-empty instance variable for the 
wastebasket can be implemented. The 
wastebasket’s drag-and-drop behavior, pop- 
up menu, and settings notebook can also be 
customized, as in Figure 4. 


* wpInitData—Overriding this method allows 
objects to initialize their instance data. In this 
case, the auto-empty flag is initialized to false, 
disabling the automatic emptying feature. 


® woSetup—This method allows the 
wastebasket to support a setup string, 
specified at object creation to initialize objects. 
A setup string can be specified using the Class 
Hierarchy Browser in the OS/2 2.0 Toolkit. 
The \OS2\INI.RC file shows examples of the 
desktop objects and corresponding setup 
strings. 


The wastebasket supports a setup string that 
sets the initial value of the auto-empty flag 
using AUTOEMPTY=TRUE or AUTOEMPTY=FALSE. 


© wpModif yPopupMenu—This method allows 
“Empty now” to be added to the pop-up menu 
by calling the _wpInsertPopupMenuItems method. 


© wpMenultemSelected—This method verifies that 
“Empty now” has been selected. If it has, the 
folder method _wpDeleteContents is called to 
delete all items in the wastebasket. If a 
different menu item is selected, the parent 
method is called so the folder class may 
process the menu selection. 


* wpSaveState—This method is called when the 
Workplace Shell makes an object dormant, 
during shutdown or when the folder 
containing the object has been closed for a long 
time. All instance data introduced by the class 
can be saved within this method. In the case of 


the wastebasket, the value of the auto-empty 
flag is saved using the wpSaveData method and 
the index IDKEY_AUTOEMPTY. 


* wpRestoreState—This method is called by the 
Workplace Shell when a dormant object is 
awakened, restoring the instance data to its 
previous state. WpRestoreState makes the auto- 
empty flag persistent between system boots. 


* wpQueryStyle—The wastebasket overrides this 
method to modify style flags for an object. The 
OBJSTYLE_NOCOPY flag is or’ed to keep the 
wastebasket from being copied, to prevent 
“Copy...” from appearing in the pop-up menu, 
and to disallow a drag-and-copy operation. 
You could also prevent the wastebasket from 
being deleted by or’ing the OBJSTYLE_NODELETE 
flag. (The OS/2 2.0 PM Programming 
Reference section lists all available style flags.) 


* wpDrag0ver—This method is one of the most 
important for the wastebasket; it emulates the 
shredder, allowing users to drop only 
deleteable objects. If an undeletable object such 
as System Settings is dragged to the 
wastebasket, the “cannot drop” icon is 
displayed. The style of all items being dragged 
must be checked to make sure they don’t have 
the OBJSTYLE_NODELETE flag setting. 


* woDrop—This method is called when items are 
dropped on the wastebasket. Although it is not 
done in the example, wpDrop could be 
overridden to put up a message box 
prompting the user to continue or cancel the 
drop operation. 


® woAddFolderIncludePage—This method is 
overridden to delete the Include page from the 
settings notebook. This is the one method in 
which the parent method is not called, keeping 
the code that inserts the Include page from 
running. 


* woAddSettingsPages—This method adds an 
auto-empty page to the settings notebook, first 
filling in a PAGEINFO structure that includes 
information about the auto-empty dialog. The 
pCreateParams field is passed to the dialog 
procedure upon initialization. By passing the 
wastebasket handle, the dialog can reference 
the wastebasket, call the Query/SaveAutoEmptyFlag 
methods, and manage the value of the 
checkbox, as in Figure 5. 
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[ARERR RAIA AIRE ERR RR RRR REE EERE ES AAA AAA AA AAA AA AAAI AAR AAA AAA A KARA IA AEA 
* METHOD: QueryAutoEmptyFlag 
* PURPOSE: Gets the instance data and returns the flag 
* INVOKED: From DlgProc 
FACES I AK EE EEE EE / 
SOM_Scope BOOL SOMLINK wpwstb_QueryAutoEmptyFlag(WPWastB *somSelf) { 
WPWastBData *somThis = WPWastBGetData(somSelf);/* get data */ 
return _bAutoEmpty ; 





} 
SERRE OSG EER RRR 
* METHOD: SetAutoEmptyFlag 
* PURPOSE: Gets the instance data and sets the flag 
* INVOKED: From DlgProc 
EEEAEEAALESELASERAARAAER AKER ARERAREAA EES AEE REESE RER AE ER EEE REAEEEEESEES EEE SS / 
SOM_Scope BOOL SOMLINK wpwstb_SetAutoEmptyFlag(WPWastB *somSelf , 
BOOL bAutoEmpty) { 
WPWastBData *somThis = WPWastBGetData(somSelf) ; 
_bAutoEmpty = bAutoEmpty ; 
return (BOOL) 0; 
} 
SEBAGO EBACE EE 
* METHOD: wpInitData 
|  * PURPOSE: Initializes instance data 
* INVOKED: By Workplace Shell, upon instantiation of the object instance. 
Jee S SS goog GAGES ACHE HEEB a ae i bck / 
SOM_Scope void SOMLINK wpwstb_wpInitData(WPWastB *somSelf) { 
parent_wpInitData(somSelf) ; 
_SetAutoEmptyFlag(somSelf, FALSE); 
} 
Pettitt ttt itor iter t iter rit rir titi ii irr tirirtiirsr ities titer ie Le 
* METHOD: wpModifyPopupMenu 
* PURPOSE: Adds an additional “Empty now” item to the object’s context menu. 
* INVOKED: By Workplace Shell, upon display of the popup. 
| Gesobbap a addodo idol ide ado iG HEE kad obo oo aaa oa Ea Ea a / 
| SOM_Scope BOOL SOMLINK wpwstb_wpModifyPopupMenu(WPWastB *somSelf, 
HWND hwndMenu, HWND hwndCnr, ULONG iPosition) { 


_wpInsertPopupMenultems(somSelf, 9) |) || /* Insert menu item «/ 
hwndMenu, |. /* Menu handle +/ 
iPosition, /* Default position +/ 

: hmodThisClass, /* Module handle +/ 
ID_CXTMENU_WASTE, /* Menu item identifier */ 
0); /* No submenu identifier*/ 


return (parent_wpModif yPopupMenu(somSelf ,hwndMenu,hwndCnr ,iPosition)) ; 
} 
SEA E AEE EEE EEE EE EE EER ERE 
* METHOD: wpMenultemSelected 
* PURPOSE: Processes the user’s selections from the context menu. The 
* method processes only the added “Empty now” item, before 
* invoking the parent’s default processing to handle other items. 
+ INVOKED: By Workplace Shell, upon selection of a menu item by the user. 
Jaa a a oda iibb aaa E ao dodocadedecccc dd bgccrcjGGg cx / 


Figure 4: Instance method implementations (continued on page 108) 
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SOM_Scope BOOL SOMLINK wpwstb_wpMenultemSelected(WPWastB *somSelf , 
HWND hwndFrame, ULONG ulMenuld) { 
if (ulMenuId==IDM_EMPTY) /* if our new item is selected, do it. */ 
return(_wpDeleteContents(somSelf, TRUE)); 
else return (parent_wpMenultemSelected(somSelf ,hwndFrame,ulMenuld)) ; 





} 


[| RRRRAKAAARARA RE EAEREEE REAR ERR ERE AA EAAAEAE AEA EAE AKAEAE ARERR ERR EREERERER 
* METHOD wpSetup 
* PURPOSE: Sets folder properties based upon a setup string passed by the 


* object’s creator as part of the WinCreateObject() call. The 

* overridden method simply processes the AUTOEMPTY keyword to set 
* the folder’s autoempty status and period, before invoking 

* the parent’s default processing to handle all other keywords. 


* INVOKED: By the Workplace Shell, upon instantiation of the object. 
HAKKAR AEA AEA AREA EAE AERA EAE EAA AREA EAE RE AEE EERE EERE EEE EE ERE / 


SOM_Scope BOOL SOMLINK wpwstb_wpSetup(WPWastB *somSelf, PSZ pszSetupString) { 


BOOL rc; 
CHAR szValue[256] ; 
ULONG cbValue=256; 


rc = parent_wpSetup(somSelf ,pszSetupString) ; 
if (_wpScanSetupString(somSelf ,pszSetupString, (PSZ)” AUTOEMPTY ” , 
szValue, &cbValue) ) 
if (!strcmp(szValue,”TRUE”)) _SetAutoEmptyFlag(somSelf, TRUE); 
else _SetAutoEmptyFlag(somSelf, FALSE); 
return rc; 
} 
[3A IA A RATA A AAA IAA AAA A ATA A AAA AAA 
* METHOD: wpSaveState 
* PURPOSE: Saves the object instance’s persistent state data. The 


* overridden method simply saves the autoempty info , then invokes 
* the parent’s default processing to handle any other instance 
* data defined by ancestor classes. 


* INVOKED: By the Workplace Shell, when the object becomes dormant. 
FEI RIAA AAR AAA AAA AAA A AAA AAA AIA AAA ARIA A AAAI / 
SOM_Scope BOOL SOMLINK wpwstb_wpSaveState(WPWastB *somSelf) { 
BOOL rc; 
BOOL bAutoEmpty ; 
rc = parent_wpSaveState(somSelf) ; 
bAutoEmpty = _QueryAutoEmptyFlag(somSelf) ; 
_wpSaveData(somSelf ,_somGetClassName(somSelf) , IDKEY_AUTOEMPTY , 
(PBYTE) &bAutoEmpty ,sizeof(BOOL)); 
return rc; 
} 
Pettitte ttt i titi Torii ir itr iri rir irri rior rr rrirririrorr rrr iiiieri iiss ts. 
* METHOD: wpRestoreState 
* PURPOSE: Restores the object instance’s persistent state data. The 


* overridden method simply restores the autoempty data, then 
* invokes the parent’s default processing to handle any other 
* instance data defined by ancestor classes. 


* INVOKED: By the Workplace Shell, when the object becomes awake. 
FARA AAA AA AA AAA | 


Figure 4: Instance method implementations (continued on page 109) 
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SOM_Scope BOOL SOMLINK wowstb_wpRestoreState(WPWastB *somSelf , 
ULONG ulReserved) { 

BOOL rc; 

BOOL bAutoEmpty ; 

ULONG cbValue = sizeof (BOOL): 

rc = parent_wpRestoreState(somSelf ,ulReserved) ; 

if (_wpRestoreData(somSelf ,_somGetClassName(somSelf) , 

IDKEY_AUTOEMPTY , (PBYTE)&bAutoEmpty ,&cbValue) ) { 

_SethutoEmptyFlag(somSelf ,bAutoEmpty) ; 
if (bAutoEmpty) _wpDeleteContents(somSelf, TRUE); 

} /* endif */ 

return rc; 





} 
eH Ea SCHEER G SCC HE GGG GOOG EE 
* METHOD: wpQueryStyle 
+ PURPOSE: Allows us to force a style such as OBJSYTLE_NOCOPY or NODELETE 
* INVOKED: By the Shell, to when it wants to copy the object 
dade SE HES Aa eo da aa aa ao ao bao Ha ia Rao oa EEE / 
SOM_Scope ULONG SOMLINK wpwstb_wpQueryStyle(WPWastB *somSelf) { 
return (parent_wpQueryStyle(somSelf) | OBJSTYLE_NOCOPY) ; 
} 
[FREER RAEAEEES EEE EAERE EASE ASERS EER ERE EAE AEE SEERA EEAEEAEAS ERE EEE EREEREREERE EES 
* METHOD: wpDragO0ver 
* PURPOSE: To detect if the user is trying to drag undeletable objects to 
+ the wastebasket. If they are, we will put up the no-drop sign. 
+ INVOKED: By the Shell, when object(s) are dragged over the wastebasket. 
door SSS HE ao dea aa Sa GE GG SSCS GG OGRE / 
SOM_Scope MRESULT SOMLINK wowstb_wpDragOver(WPWastB *somSeLf, 
: HWND hwndCnr, PDRAGINFO pdrgInfo) { 
| MRESULT mResult; 
| USHORT usItem: 
SOMAny * Object; 
PDRAGITEM pDragitem; 
/*Get parent call to figure out if it is droppable.*/ 
mResult = parent_wpDragO0ver(somSelf, hwndCnr, pdrgInfo); 
/*Parent says NEVERDROP then return */ 
if (SHORTIFROMMR(mResult)==DOR_NEVERDROP ) 
return(mResult) ; 
/*Check if all items are acceptable */ 
for (usItem=0; usItem < pdrgInfo->cditem; usItem++) { 
if ( !(pDragItem = DrgQueryDragitemPtr(pdrgInfo,usItem)) ) 
return(MPFROM2SHORT (DOR_NEVERDROP , DO_DEFAULT)) ; 
if ( !(pDragItem -> ulItemID) ) /*No SOM Object ID+*/ 
return(MPFROM2SHORT (DOR_NEVERDROP ,DO_DEFAULT)) ; 
if (!(Object=0BJECT_FROM_PREC(pDragItem->ulltemID))) /*Get ObjectID */ 
return(MPFROM2SHORT (DOR_NEVERDROP ,DO_DEFAULT)) ; 
if (_wpQueryStyle(Ob ject) &0BJSTYLE_NODELETE) /*Check if deletable*/ 
return (MPFROM2SHORT (DOR_NEVERDROP , DO_DEFAULT)) ; 
if (pdrgInfo -> usOperation == DO_COPY || /#*Check no Link or Copy+/ 


pdrgInfo -> usOperation == DO_LINK) /*If so then return no */ 
return(MPFROM2SHORT (DOR_NEVERDROP ,DO_DEFAULT)); 
} /*Loop throughall items+/ 


Figure 4: Instance method implementations (continued on page 110) 
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return (MPFROM2SHORT(DOR_DROP ,DO_MOVE)) ; 
} 
[REREEEAERAEEREEER ERE ERE ERE ERE EES EER EEE ERR EREEERE EASE EAE ERE EEEEESE RAE EREEES 
* METHOD: wpAddFolderIncludePage 
* PURPOSE: Allows us to remove the include page so the user can’t hide any 
* items in the waste basket. It is important to have all items 
* visible so that something important is not accidentally emptied. 
* INVOKED: By the Shell, when the page is added to the settings view. 
FEC RE BAAR RR BORER TORR IIA AAR RIAA TAREE I TRAE / 
SOM_Scope ULONG SOMLINK wpwstb_wpAddFolderIncludePage(WPWastB *somSelf, 
HWND hwndNotebook) { 
WPWastBData *somThis = WPWastBGetData(somSelf); 
WPWastBMethodDebug(“WPWastB” , “wpwstb_wpAddFolderIncludePage” ) ; 
return TRUE; 
} 


ERASE RR RRR EE EAE IIIA IIIA IAI TATA AH REE 

* METHOD: wpAddSettingsPages 

* PURPOSE: Allows us to add the AutoEmpty page to the settings view. 

* INVOKED: By the Workplace Shell, when the settings view is openned. 

doe S SCS CAAA SSS eo gga aga GG GGA AAR A i bee / 

SOM_Scope BOOL SOMLINK wowstb_wpAddSettingsPages(WPWastB *somSelf, 

HWND hwndNotebook) { 
PAGEINFO pageinfo; 
if (!parent_wpAddSettingsPages(somSelf , hwndNotebook) ) 
return (FALSE); 

memset (&pageinfo,sizeof(PAGEINFO),0); /* clear the struct */ 
pageinfo.cb = sizeof (PAGEINFO); 
pageinfo.pfnwp = DlgProc; 
pageinfo.resid = hmodThisClass; 
pageinfo.pCreateParams = (PVOID)somSelf; 
pageinfo.dlgid = ID_DLG_AUTOEMPTY; 
pageinfo.usPageStyleFlags = BKA_MAJOR; 
pageinfo.usPageInsertFlags = BKA_FIRST; 
pageinfo.pszName="“Auto Empty” ; 
return _wpInsertSettingsPage(somSelf, hwndNotebook, &pageinfo) ; 





Figure 4: Instance method implementations (continued from page 109) 
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eee REE EEE EE Ee 
+ PROCEDURE NAME: DlgProc 

* description: Dialog procedure for auto-empty page dialog 

aS a a dodobeoedec agi gg ga odo dda gaa a / 
MRESULT EXPENTRY DigProc(HWND hwndD1lg,ULONG msg,MPARAM mp1,MPARAM mp2) 
SOMAny * Wastebasket; 
BOOL bAutoEmpty ; 
switch (msg) { 

case WM_INITDLG: 





/+ Determine message class */ 
/* Dialog being initialized +*/ 


/* Store SOM pointer in window word QWL_USER */ 
WinSetWindowULong(hwndDlg, QWL_USER, (ULONG)LONGFROMMP(mp2)) ; 
Wastebasket = (WPWastB +) LONGFROMMP(mp2) ; 

if (_QueryAutoEmptyFlag(Wastebasket) ) 


WinCheckButton(hwndDlg, ID_CB_AUTO, 1); 
break; 
case WM_CONTROL: 
Wastebasket = (WPWastB *)WinQueryWindowULong(hwndDlg, QWL_USER); 
if (SHORTIFROMMP(mp1)==ID_CB_AUTO) 
&& (SHORT2FROMMP (mp1 )==BN_CLICKED) ) 
if (WinQueryButtonCheckstate(hwndDlg,ID_CB_AUTO)) 
_SetAutoEmptyFlag(Wastebasket, FALSE) ; 
else _SetAutoEmptyFlag(Wastebasket, TRUE) ; 
_wpSaveDeferred(Wastebasket) ; 
break; 
} 
return(WinDefDlgProc(hwndDlg, msg, mpi, mp2)); 
} 





Figure 5: Notebook page dialog procedure 
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There must be a 
shift in thinking 
for the developer 
used to coding a 
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host interface. 


GUI 
Thinking in 


Presentation Manager 


by Christine Grau and Diane Lovelett 


This article describes some of the differences we 
noticed while coding host and workstation 
interfaces. Our experience is primarily with 
Presentation Manager (PM) on the workstation 
and the Interactive System Productivity Facility 
(ISPF) and Dialog Tag Language (DTL) on 
multiple virtual storage (MVS). 


‘Tree are several reasons why you might 
port a host application and connect to a 
workstation. The main reason is that a 
workstation interface is a graphical interface 
that provides flexibility and capability through 
a wide choice of fonts, numerous colors, and a 
wide variety of controls that allow 
programmers to improve an application’s 
overall usability. 


A workstation application changes 
dynamically, allowing extensive interface 
tailoring. This feature allows programmers to 
create precise interfaces that communicate to 
the user exactly the task at hand. 


Workstation applications increase user 
response times, especially in the area of screen 
painting. For cooperative processing 
applications, workstation applications can, in 
some cases, offload some of the work from the 
host, saving millions of instructions per second 
(MIPS), leading to actual dollar savings for the 
organization as a whole. 


The applications are usually object-oriented 
and conform to the messy desk and workplace 
models. Additionally, OS/2 provides 
multitasking, which allows for improvements 
in performance and enables multiple copies of 
an application to run at the same time. 


Whatever motivates your decision to port your 
application from the host to the workstation, 
there must be a shift in thinking for the 
developer used to coding a host interface. The 
developer must understand the differences 
between the nature of each interface and the 
differences between the techniques used to 
create each interface. 


GRAPHICAL VS. 
NONGRAPHICAL 
INTERFACES 


A PM interface provides a graphical 
environment, A traditional program gets user 
input from the keyboard and displays output 
to the screen. 


As stated by Charles Petzold in Programming 
the OS/2 Presentation Manager (Microsoft Press, 
1989): 


.@ graplical windowing environment can inspire 
program developers to create a radically new and 
environment of Presentation Manager ts rich in 
function—programs can use graphics and formatted 
text to convey a high density of information to the 
user, 


... With the addition of a mouse, the screen becomes a 
potential source of user input, Logie within 
Presentation Manager assists the application in 
obtaining user input from various controls on the 
screen, such as menus, scroll bars, buttons, and 
dialogue boxes. The interaction between the mouse 
and screen narrows the gap between user and 
program, 


Because a PM interface is a graphical interface, 
it can be thought of as three-dimensional, even 
when the interface contains traditional controls 


i. °° :6 OS eS |. SO 


and not graphics per se. A host interface can be 
thought of as two-dimensional. What you see 
when you first look at a Presentation Manager 
interface is not the whole picture, while what 
you see when you look at a host interface is the 
whole picture. For example, a PM drop-down 
combo box looks compact and graphically 
small. However, when you click on the drop- 
down button, a new view is seen. Suddenly, an 
entire list of items is visible, which can once 
again be hidden with another click. This all 
occurs without leaving the main window. 


As a result, you think differently when 
designing a PM interface than when designing 
a host interface. For example, you can put a lot 
of data into a single window without crowding 
the window. If you first designed a window on 
Presentation Manager and tried to design a 
comparable window on the host, it would be 
difficult because the host cannot provide the 
function in the same way, cannot display as 
much data in a single panel, and must use less 
flexible techniques to achieve similar results. 
The results may be similar, but never the same. 


Conversely, you can redesign a host interface 
into a PM interface without limitations and 
with an increase in function. Additionally, a 
PM interface allows you a greater variety of 
font styles and sizes, colors, and extensive 


graphics. 


Designing a PM interface is a more intriguing 
and difficult task than designing a host 
interface because the tools available for 
designing a PM interface are varied and 
extensive. Because the tools for designing a 
host interface are limited, there are fewer 
design decisions to be made and interface 
design is easier and less time-consuming. 


A MESSY DESK VS. A 
HIERARCHICAL ENVIRONMENT 


A PM interface gives users a messy desk 
environment in which to work. A host 
interface provides a hierarchical environment 
to users. The PM interface also allows 
multitasking. Switching between applications 
or within an application can be done with a 
keystroke or a click of the mouse. The host, on 
the other hand, often forces you to exit the 
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application you are in before beginning 
another task. 


When programming for the host, 
programmers must not only do extensive task 
analyses to determine what tasks their users 
will do, they must also understand in what 
order they will do these tasks. The finished 
application must allow users to perform 





certain tasks in a specific order. 


PM TERMS 


Check box 
Client window 


~ Combo box 
- Container 


Dialogue window 
Entry field 

Frame window 
Group box 

Icon 

List box 

Menu 

Message box 
Multiple line entry 


| Notebook 
Pushbutton 


Radio button 


Scroll bar 

Slider bar 

Spin button 
Static text 
System menu 
Value set control 


HOST TERMS 


Selection list 


Pop-up 
Entry field 


Panel 


Selection list 
Menu 
Pop-up 

Edit session 


Program function (PF) keys, enter key, or 
commands 


PF8 or PF7 (or other defined PF keys) 


Static text 








Table 1; Presentation Manager terms-vs, host terms 


A workstation imterface-allows users to choose 
when they will do certain tasks; they are not 
tied to the hierarchy of the program. 


INTERFACE ELEMENTS 


PM interface elements, such as windows and 
controls, offer more selection and functions 
than their counterparts on the host, such as 
panels, program function (PF) keys, and pop- 
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Interface elements are static. PM controls can 
dynamically change based on something 
chosen by the user. An entire PM window can 


ups. The host screen and workstation window 
are comparable entities. Table 1 compares PM 
and host interface elements to allow you to see 


relationships among the various elements. 





/* Message Loop */ 


while (WinGetMsg(hab, (PQMSG)&qmsg, (HWND)NULL, 0, 0)) 
WinDispatchMsg(hab, (PQMSG)&qmsg) ; 





Figure 1: The Presentation Manager message loop 


MRESULT EXPENTRY WinProc(HWND hwnd,USHORT msg,MPARAM 
mp1 ,MPARAM mp2) 
{ 


switch (msg) 
{ 
case WM_CREATE : 


/* code to create window and initialize data +/ 


break; 
case WM_PAINT : 


/* code to paint the screen +#/ 


break; 
case WM_SIZE : 


/* code to when a window is resized */ 


break; 
case WM_DESTROY : 


/* code to destroy a window and free resources +/ 


break; 
default 
return (WinDefWindowProc(hwnd, msg, mp1, mp2)); 
} 
return (FALSE); 
} 


Figure 2: Skeleton window procedure 





be moved or resized, something that is 
impossible on a host screen. 


On the host, accelerated paths to functions can 
be provided with a command language or 
through a set of 24 PF keys. However, the 
workstation can provide many more functions 
with accelerator keys. 


An additional drawback to the host command 
language mechanism of providing fast paths is 
that these commands are not illustrated next to 
the menu items they represent. The learning 
required to remember the commands is 
separate from becoming familiar with the 
interface. With PM, the accelerator key for a 
function is visible with the function. 


The PM drag-and-drop function provides 
users with direct manipulation capabilities. 
With a drag-and-drop function, a user can 
drag a file, which is represented as an object, to 
an icon of a printer to print the file. On the 
host, users must type commands or follow an 
application's path to print a file and cannot 
directly manipulate the file object. 


Although not specifically an interface element, 
the PM window gives users a multiapplication 
environment in which to work. A user can 
have multiple applications open on one screen, 
allowing interaction, such as cut and paste, 
among many different types of applications. 
On the host, users can have at most two 
applications available at a time through the 
split screen capability. 


First-time Presentation Manager programmers 
will find that the learning curve is long and 
difficult because of the large number and 
complexity of PM interface elements. 


MESSAGE-BASED VS. 
STRUCTURED PROGRAMMING 


In Programming the OS/2 Presentation Manager, 
Charles Petzold notes that the biggest hurdle 


The large number of PM interface elements 
allows programmers to be more creative in 
displaying, retrieving, and connecting data. 


in moving from a host to a PM interface is 
grasping the concept of messaging. While host 
interface programming is accomplished 
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through traditional structured programming, 
PM interface programming is done exclusively 
with messaging. 


The main procedure of a PM application 
always contains the code fragment shown in 
Figure 1. 


In the PM message loop, control flow in PM is 
done with message passing. Messages can be 
sent directly to a window or can be queued. 
Imagine an application where the interaction 
between the user and the window is 
accomplished by sending a message for each 
task that the user tries do. Every key stroke or 
mouse click causes an invisible message to be 
sent to a message queue. 


The message queue is an object in PM whose 
function is to store these messages and 
dispatch them to the appropriate window by 
switching control to associated window 
procedure. This loop continues to execute until 
the application is told to quit. A skeleton of a 
PM window procedure is shown in Figure 2. 


The window procedure looks very much like a 
normal structured procedure. A message 
drops through and finds the appropriate case 
statement. If nothing is found, it falls through 
and control goes to a default window 
procedure. At the end of the message 
processing, a return statement returns control 
to the message processing loop. 


A window can send messages directly to 
another window or send messages back to 
itself. This implies that a window procedure 
can call itself, requiring languages used within 
the window procedure to be reentrant. 


Programming a host interface with DTL or an 
interactive system productivity facility is 
different. Panels are defined separately in 
panel definition files. Typically, control flow is 
more sequential and structured. For example, 
displaying a window is often part of a total do- 
while statement. Typical logic for displaying a 
panel is shown in Figure 3. An example of 
code that performs the task in Figure 3 is 
shown in Figure 4. 


First-time Presentation Manager programmers 
will find that the transition to a message-based 


architecture is a difficult one with a long 
learning curve. 


OBJECT-ORIENTED VS. 
NON-OBJECT-ORIENTED 





Presentation Manager is an object-oriented 
approach to creating interfaces, while the 
traditional host method of creating interfaces 
can be characterized as structured 
programming. 


LOGIC FOR HOST DISPLAY OF PANEL 


1. Initialize fields on panel. 
2. Do while user does not hit exit: 
a. Display the panel. 
b. Check field one. If OK, continue. If not OK, send the user a 
message; go to top of loop. 
c. Check field two. If OK, continue. If not OK, send the user a 
message; go to top of loop. 
d. All fields are OK: Display second panel. 
3. End do. 





Figure 3: Logic for host display of panel 


In PM, each interface element can be viewed as 
an object. For example, if a user moves the 
mouse pointer and clicks on the Exit button, 
the window disappears. In this situation, the 
user performs some action (clicking the 
mouse) on an object (the button), and a 
message is sent to the object receiving the 
action (the button). The receiving object then 
uses some method to interpret the action. In 
this case, the button interprets the action as a 
signal to make the window disappear. 


PM can be characterized as event-driven 
programming and is actually a simulation of a 
sequence of events. In contrast, structured 
programming is characterized more by the 
traditional process-state method. A program is 
a set of instructions that saves values into 
storage locations (variables), continually 
modifies their values, and moves them to other 
storage locations. By examining these storage 
locations, the programmer determines the state 
of the program and the results. 
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main() 


{ 
/* 1, Initialize fields on panel. 


BlankandNull(sizeof(Mfield1), Mfield1); 
BlankandNull (sizeof (Mfield2), Mfield2); 


/* 2. Do while user doesn’t hit exit. 


while (!ExitKey) 
{ 


/* a. Display the panel. 

rc = ISPLINK(“DISPLAY “, “PANLMAIN”, “ “, reqfield); 
/* Get return code from panel display. 

PanelRc = rc; 


/* If panel return code was 8, (exit or cancel), set ExitKey to 
/* on. Otherwise, process main panel. 


if (PanelRc == 8) 
ExitKey = ON; 
else 


{ 


/* Convert value of ACTBRCH variable to integer so a switch 
/* can be done on it. 


SetValue(&ActionBarValue, ActionBarChoice); 
/* b. Check field one. If ok, continue. 
/* Call routine to process field 1. 
FieldiRc = FieldiProcess(&Request) ; 
if (!FieldiRc) 
| { 
/* c. Check second field on panel. If ok, continue. 
Field2Rc = Field2Process(&Request) ; 


if (!Field2Rc) 
{ 


/* d. Call routine to display second panel. 


ProcessNew(&Request) ; 


} 6 /* end if 
} /* end if 
} /* end else 
} /* end while + / 
exit; 
} /* * End of main * 


Figure 4: Sample host program for displaying a panel 


+/ 


*/ 
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In traditional programming methods, the 
programmer addresses such issues as 
complexity and reuse by using abstraction 
mechanisms such as procedures, modules, 
and abstract data types. Procedures allow 
programmers to execute different tasks 
repeatedly. Modules allow programmers to 
share data across an entire application and 
separate parts of an application to keep some 
information only accessible locally. Abstract 
data types, in turn, allow programmers to 
define their own data types similar to system- 
defined data types. 


PM, as an object-oriented system, does not 
organize information in the same way. Data is 
thought of as objects and each object belongs 
to a group, called classes. Classes are then 
organized in a hierarchy where each class can 
be broken into subclasses, A class determines 
the behavior of an object, and subclasses are 
said to inherit the properties of their 
superclasses. Classes and inheritance allow 
reuse in PM. By organizing data in classes, 
code is reused by all instances of a class. 
Through inheritance, a subclass can 
automatically reuse methods that its 
superclass manifests. 


Another difference between host and PM 
programming is how data is accessed. The 
only way an object can be accessed in PM is 
through the object’s handle. A handle is a 
unique identifier for an object in PM. 
Typically, to perform an operation on an 
object, the programmer identifies the object 
through its handle and sends it a message. On 
the host, programmers instead associate 
variables with a particular interface element to 
store information about the element. 


For example, to store text in an entry field and 
information about the entry field’s maximum 
length, a programmer would typically create 
an abstract data type or store each in two 
variables. To get to this data, the programmer 
then has to access two storage locations. In 
PM, data is encapsulated. To access anything 
needed in an object, the programmer need 
only know its handle. 


DYNAMIC VS. STATIC 
INTERFACES 


A PM interface can dynamically change 
throughout the life of the application, while a 
host interface is static. The behavior of a PM 
interface element can change throughout the 
life of the program through messaging. An 
application can send a message to a control to 
change its state from write-mode to read-only. 
A PM window’s appearance is always 


changing. 





Presentation Manager allows developers to 
dynamically interrupt system processing to 
tailor controls or processing. On the host, 
panels are predefined and displayed in a fixed 
way. 


The interaction 
between mouse 
and screen 
narrows the gap 
between user 
and program. 


In general, the difference in the way you 
define host interface elements and the way you 
define PM interface elements’ behaviors is that 
PM interface elements’ attributes and behavior 
are defined in the application program or 
predefined in a .DLG file. Host interface 
elements’ attributes and behavior are always 
predefined in panel definition files. 


Because you can change things dynamically 
with a PM interface, there is much more work 
involved in designing and coding it than for a 
host interface. As a PM programmer, you must 
spend more time designing the interface by 
determining which events will signal which 
changes to the interface. As a host 
programmer, you do not need to do this up- 
front design work or coding to implement the 
more complex design. 


MULTIPROGRAMMING 
AND MULTITASKING 


PM programming introduces the concepts of 
multitasking and multiprogramming. Host 
programmers will have to become familiar 
with various concepts to code a multitasking 
application. These concepts include 
semaphores, queues, threads, processes, and 
so on. These concepts are not trivial, but once 
learned can add lots of function and potential 
to an application. 
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an interface 
programmer. 


A consideration when developing a 
hierarchical structured program vs. 
developing an object-oriented program is code 
review, It is easier to review code for a 
structured program. You simply follow the 
code’s logic, stepping through each instruction 
in sequential order. For an object-oriented 
program, it is difficult to tell which object will 
be functioning at which time. For a PM 
program, each case in a switch statement may 
represent processing for an object. However, 
you cannot tell which case statement will get 
control at any given time. 


It is difficult to debug a PM program when 
you don’t know exactly when each statement 
gets control. Not only is the program 
processing case statements for new objects 
defined by the programmer, it is also handling 
PM system actions, such as creation of 
windows, system-generated messages, and so 
on. It is easier to debug a hierarchical 
structured program than an object-oriented 
one. 


Porting a host workstation interface does not 
necessarily mean that data will also reside on 
the workstation. The programmer needs to 
think about where data will be residing and 
how much processing will be done on the host 
vs. the workstation. Design decisions must be 
made about what type of architecture will be 
used, whether it is client/server, cooperative 
processing, or distributed. 


Performance, data integrity, and data recovery 
all become key issues when deciding whether 
to port a host application to the workstation. In 
fact, these issues are probably the biggest 
obstacles in deciding to port a host application 
to the workstation. If your application’s 
interface and data repository both reside on 
the host, you can more easily ensure 


performance, data integrity, and data recovery. 


In deciding to move to the workstation, these 
issues become much more complex and 
difficult to implement. 


Estimating effort and time management is 
difficult with PM programming. For the first- 
time PM programmer, there is a long learning 
curve. For the novice or experienced PM 
programmer, interface design involves a lot of 
research. There will be times where you will 


not know how to do a specific type of 
implementation and research will be required. 


There are lots of tricks in PM programming, 
and there are times when you think a task is 
difficult, but will actually turn out to be quite 
easy. There are times when implementation 
seems straightforward, but the actual coding 
turns out to be difficult. Since there is a long 
history of experience with host programming, 
its schedules are more easily estimated and 
adhered to. 


CONCLUSION 


There are many considerations when deciding 
whether to port a host application to the 
workstation. The decision to move to the 
workstation hinges on whether there are 
adequate tools available to create the 
workstation interface, provide the host- 
workstation communication protocol, and 
provide data integrity and recovery. 


If you have already decided to port your host 
application to the workstation, the biggest 
hurdle you will encounter is changing the way 
you think as an interface programmer. 
However, learning to think like a PM 
programmer is becoming easier as PM 
programming tools proliferate. Currently, the 
WorkSet/2'™ (the PM Developer's Toolkit) 
comes with a dialogue editor that automates 
panel design as well a generates code for your 
panel and an information presentation facility 
(IPF) that allows you to automate help-pane! 
generation. 


If you have not yet decided to make the 
transition to workstation interface, the decision 
must be made by weighing the advantages of a 
workstation interface against the cost of 
creating it. Even though the shift in thinking 
and the learning curve required to become a 
PM programmer make the cost of the 
transition high, the benefits gained by shifting 
to a PM interface are many. The PM interface is 
an intuitive, object-action, and event-driven 
interface that conforms to the criteria outlined 
in the SAA CUA91 Reference. The PM 
application model makes creating user- 
friendly, consistent interfaces easy. PM's 
object-orientation encourages principles such 
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Demystifying 


Custom Controls 


by Mark A. Benge and Matt Smith 


Since the early days of OS/2 1.1, many developers 
have wondered how to create controls that act like 
the push button, scroll bar, and entry field controls 
provided by the system. Most of the necessary 
information has been present within the OS/2 
reference manuals, but scattered throughout them. 
Only through deduction and painstaking 
observation of custom controls that operated exactly 
like those that the system provided could you create 
a custom control. 


This article, the first of two parts, pulls together all 
the information found within the references and 
explains areas that have been missing. From this 
article and the accompanying example control 
source code, you will be able to create your own 
custom controls. 


WHAT IS A CONTROL? 


| see OS/2 Presentation Manager (PM), a 
control is really just another window. In 
real terms, it is very similar to any client 
window you create in your current OS/2 PM 
applications. You need to register the class of a 
control just like you would with a client 
window, and the control is created in a similar 
manner to your client window through the 
WinCreateWindow function. The major difference 
is that the control can also be created through a 
dialogue template that resides in the 
application’s resources. 


CONTROLS IMPLEMENTATION 
PRIMER: THE MAGIC REVEALED 


The makeup of a custom control is generally 
easy to follow and is dependent on the 


complexity of the control. For example, a 
complex control like the container that is 
found within OS/2 PM contains 
approximately 42,000 lines of code, whereas 
our example image button contains almost 
2,100 lines of code and most of those lines are 
comments. 


The most critical issue facing a control is data 
encapsulation and reentrancy. This is easily 
solved since the designers of OS/2 PM 
allowed for window words that you reserve 
through the WinRegisterClass function shown in 
Figure 1. 


The last parameter, cbWindowData, is used to 
specify the number of window words you 
need. For custom controls, you will need at 
least eight bytes, where the first four bytes are 
used as the QWL_USER user storage and the 
second four bytes for the internal control data 
that will record pertinent information about 
the instance of the control. 


The internal control data structure is simply a 
structure that contains information about the 
control, such as size and position, current 
style, owner and parent window handles, and 
so on. You can place anything you deem 
necessary in this structure, since you totally 
control its contents, and it is private to the 
control. 


This structure allows for data encapsulation 
and reentrance. Figure 2 shows part of the 
control structure used for the image button 
and Figure 3 shows how you place the address 
of the structure within the reserved window 
words and how to retrieve it. 


This is part of the magic, as we will call it, of 
creating a custom control that hasn’t been fully 


Winter 1993 





explained in the OS/2 Programmer's Reference. 
The second part of the magic is the messages 
that the control handles. Table 1 outlines most 
of the messages you may want to handle in 
your custom control. 


The third part of the magic (and this is real 
magic since it isn’t documented anywhere) is 
the presentation parameters. These magical 
mystical creatures provide some of the most 
powerful features found within OS/2 PM. The 
nice part about the presentation parameters is 
that when you are dealing with them ina 
custom control, you really don’t have to 
concern yourself with them except where you 
want. 


One area misunderstood with presentation 
parameters is how they arrive at the control. 
WinCreateWindow through the pPresParams 
parameter in Figure 4, allows for a set of 
presentation parameters to be passed to the 
contro]. A second method is through the 
resource script file as shown in Figure 5. Here, 
the values are preset, and they ultimately are 
passed to the control through the 
WinCreateWindow function when the control is 
created by the dialogue manager. The last 
method is through the WinSetPresParam 
function. In this case, the control won't receive 
a packet of presentation parameters like those 
through the WinCreateWindow function but will 
receive the WM_PRESPARAMCHANGED message. 


Although the presentation parameters are 
passed to the control through the WM_CREATE 
message in the CREATESTRUCT parameter, they 
are set by OS/2 PM on behalf of the control 
and only those of interest need to be 
determined by the control. One method is to 
walk the presentation parameters list that is 
passed to the control through the CREATESTRUCT 
parameter and the pPresParams field. The only 
concern here is that the presentation parameter 
may have been set as an index value rather 
than a RGB color. 


Therefore, you should query for the 
presentation parameters that are of interest to 
you and query for the RGB color values. This is 
done by using the QPF_ID*COLORINDEX flag with 
WinQueryPresParams. Therefore, when you do the 
painting of the control, you switch to RGB 
color mode from index mode using the 
function GpiCreateLogColorTable with the 
LCOLF_RGB flag, allowing you to use exact colors. 


Even though the presentation parameters have 
been set for you by the WinCreateWindow 
function, you need to query for them since you 
will not receive the WM_PRESPARAMCHANGED 
message. You can either query for the 
presentation parameters of interest during the 
processing of the WM_CREATE message or each 
time you paint the control. We suggest that 
you do the former and record the values 
within the internal control data, making the 
painting of the final control as fast as possible. 





WinRegisterClass ( HAB hab, PSZ pszClassName, PFNWP fnWndProc, ULONG 


f1Style, ULONG cbWindowData ); 


Figure 1; WinRegisterClass definition 


#define IBS_UP 0x0001 
#define IBS_DOWN 0x0002 
#define IBS_DISABLED 0x0004 
#define IBS_CAPTURE 0x1000 


/* --- Internal Structures 
typedef struct _IMGBTN 
ULONG = id; 


ULONG flStyle; 
BOOL fFocus; 


/* Style 


HWND hwndOwner ; 
HWND hwndParent; 
} IMGBTN ; 


typedef IMGBTN *PIMGBTN; 





Figure 2: Internal control data structure 


The WM_PRESPARAMCHANGED message will only be 
received when the application uses the 
WinSetPresParam function to add presentation 
parameters and WinRemovePresParam to delete the 
presentation parameter, or when the Scheme 
Palette for the application changes. 


A good example of the message 
WM_PRESPARAMCHANGED can be demonstrated with 
the PP_FONTNAMESIZE presentation parameter. If 


Button State: 
Button State: 
Button State: 
Button State: 


imgbtn +/ 
/* ID Value 


/* Focus Flag 





Up 

Down 
Disabled 
Capture 


/* Owner Window Handle 
/* Parent Window Handle 
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you use WinSetPresParam(hWnd, PP_FONTNAMESIZE, 
7L, (PVOID)"8.Helv") to set the font of the 
control, you don’t have to worry about loading 
the font and doing all the usual messy font 
handling. When you draw the text in the 
WM_PAINT message, the presentation space 
returned to you by the WinBeginPaint function 
will have already selected the font, so you only 
have to use GpiCharString* or WinDrawText to 
draw the text for the control. Since OS/2 2.0 
now allows you to specify scalable fonts, you 
don't have to worry about those either. 





#define QUCWP_WNDP (QWL_USER + 4) /* Pointer to Internal Control Data 
/* Allocate memory for internal control data 


DosAllocMem((PPVOID)&pimgbtn, sizeof (IMGBTN), 
PAG_READ | PAG_WRITE | PAG_COMMIT) ; 


/* Save the address of the internal control data 
/* in the control’s reserved memory to allow it 


/* to be referenced as required by the control 


WinSetWindowPtr(hWnd, QUCWP_WNDP, (PVOID)pimgbtn) ; 


/* Get the address of the control info from the 
/* control’s reserved memory 


pimgbtn = (PIMGBTN)WinQueryWindowPtr(hWnd, QUCWP_WNDP) ; 








Figure 3; Accessing reserved window words 


( HWND hwndParent, PSZ pszClass, PSZ 
pszName, ULONG flStyle, LONG x, 
LONG y, LONG cx, LONG cy, HWND 
hwndOwner, HWND hwndInsertBehind, 
ULONG id, PVOID pCtlData, PVOID 
pPresParams ); 


WinCreateWindow 





Figure 4: WinCreateWindow definition 


HANDLING COLOR 


Handling color is different. Only the 
foreground and background colors are 
automatically taken care of within the 
presentation space. When the foreground and 
background presentation parameters are set, 


122 the presentation space you receive from 


WinBeginPaint will have those colors selected as 
the default colors. If the control you are 
creating only uses the foreground and 
background colors, you do not need to record 
the colors within your internal control data. If 
you want to use the disabled and highlight 
values, you need to query for them. That can 
be done during processing of WM_CREATE or just 
before you paint the control. 


When the application uses the WinSetPresParam 
or WinRemovePresParam functions, the control will 
receive the message WM_PRESPARAMCHANGED with 
an index value of the presentation parameter 
that has changed. Now, you can determine 
which presentation parameter index or RGB 
color value has been changed and whether or 
not you should query for the color value using 
the WinQueryPresParam function with the passed 
presentation parameter index value. 


You can query the color added or removed 
based on index value (that is, CLR_* or SYSCLR_*) 
or as a RGB color value using the 
QPF_ID*COLORINDEX flag. We suggest that you use 
the RGB color value since it will allow you to 
better control and display colors within the 
control. The color will be returned when a 
presentation parameter is present, and 
WinQueryPresParam will return the number of 
bytes returned. When a presentation 
parameter has been removed through the 
function WinRemovePresParam, WinQueryPresParam 
will return OL, indicating no presentation 
parameters are present for the parameter 
requested. In this situation, the control should 
revert back to its default color scheme for that 
parameter. 


Special consideration should be given to a 
condition that is not properly documented: the 
indication of a global presentation parameter 
update that happens when the user applies a 
new color scheme to the window or dialogue 
box using the Scheme Palette. The message 
WM_PRESPARAMCHANGED will be received by the 
control with a presentation parameter index 
value of 0 (contained in mp1). When received, 
the control should query the presentation 
parameters of interest to make sure that any 
color changes are recorded. 


When placing presentation parameters within 
resource script files, the PRESPARAMS statement is 
used, It allows the presentation parameters for 
the control to be specified so that when the 
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COMMAND 


BM_CLICK 


WM_ACTIVATE 
WM_ADJUSTWINDOWPOS 


WM_*SELECT 
WM_BUTTON*DOWN 
WH_BUTTONUP 
WM_CHAR 
WH_CREATE 


WH_DESTROY 


WM_ENABLE 
WH_ERASEBACKGROUND 
WM_HITTEST 
WM_MOUSEMOVE 
WM_PAINT 
WM_MATCHMNEMONIC 


WM_PRESPARAMCHANGED 


WM_QUERYCONVERTPOS 
WM_QUERYDLGCODE 
WM_QUERYWINDOWPARAMS 


WA_SETFOCUS 
WH_SETSELECTION 
WM_SETWINDOWPARAMS 


WM_SIZE 


WM_SYSCOLORCHANGE 
WM_WINDOWPOSCHANGED 


MESSAGE USAGE 


Simulates a button click. It is used in conjunction with 
WM_QUERYDLGCODE and WM_MATCHMNEMONTC. 





Registers or deregisters with the Help manager. 


Informs the control that its position or size is about to change. It 
allows the control to adjust the values if required. 


Informs the control of the starting and ending of swipe selections. 
Used to monitor mouse button presses. 

Used to monitor mouse button releases. 

Used to monitor keyboard selections for the control. 


Performs control initialization, allocates internal data structures, 
performs initial sizing of control, presentation parameters, 
and control setup. 


Provides control clean-up such as releasing resource and memory 
objects used. 


Monitors when the control is becoming enable or disabled. 
Used to erase the control background. 

Used to respond to mouse handling of the control. 

Used to monitor mouse pointer movement. 

Used to paint the control. 


Used to determine if a typed character matches a mnemonic in its 
window text. 


Used to monitor changes in presentation parameters that are 
applied to the control by the system. 


Used to provide for conversion of DBCS characters. 
Used to identify the capabilities of the control to the system. 


Used to process window parameter queries such as length of text 
and actual text retrieval. 


Used to monitor when the control is receiving focus or losing it. 
Used to highlight or dehighlight a selected item. 
Used to process window parameter settings such as setting text. 


Used to monitor size and position changes being performed on 
the control. 


Used to inform the control that a system color has changed. 


Used to inform the control that its position has changed. 


Table 1: Messages relevant to custom controls (messages in bold are used in image button example) 123 
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CONTROL " ", EF_TEXT, 262, 25, 46, 8, WC_ENTRYFIELD, 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 


CTLDATA 8, 6, 0, 0 


PRESPARAMS PP_FOREGROUNDCOLORINDEX, CLR_RED 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv Italic" 


Figure 5: Resource script showing PRESPARAMS 


POINTL apt1([2] ; 
ENTRYFDATA efd; 
PPRESPARAMS ppres; 
PPARAM pparam; 


efd.cb = sizeof (ENTRYFDATA) ; 
efd.cchEditLimit = 6; 
efd.ichMinSel = 0; 
efd.ichMaxSel = 0; 


aptl[0].x = 262L; 

aptl[0].y = 25L; 

aptl[i].x = 46L; 

aptl[i].y = 8L; 

WinMapDlgPoints(hwndParent, aptl, 2L, TRUE); 


DosAllocMem((PPVOID)&ppres, 





/* Dialog Units Conversion Points 
/* Entry Field CTLDATA 

/* Presentation Parameters Array 
/* Parameters Pointer 


sizeof (PRESPARAMS) + sizeof(PARAMS) * 2 + 16, 


PAG_READ | PAG_WRITE | PAG_COMMIT) ; 


ppres->cb = sizeof(PARAMS) * 2 + 16; 
pparam = ppres->aparam; 

pparam->id = PP_FOREGROUNDCOLORINDEX ; 
pparam->cb = 4L; 

pparam->ab = (BYTE)CLR_RED; 


pparam = (PPARAM)(ppres->aparam + (BYTE)(sizeof(PARAM) + 3L); 


pparam->id = PP_FONTNAMESIZE; 
pparam->cb = 14L; 
memcpy(pparam->ab, "8.Helv Italic", 14); 


WinCreateWindow(hwndParent, WC_ENTRYFIELD, “”, ES_MARGIN | WS_TABSTOP | WS_VISIBLE, 
apt1[0].x, aptl[0].y, aptl[i].x, aptl[i].y, hwndOwner, 
HWND_BOTTOM, EF_TEXT, (PVOID)&efd, (PVOID)ppres); 


Figure 6: WinCreateWindow with presentation parameters example 


control is created through a resource script ina 
dialogue box or window, the desired 
presentation parameters are used. Figure 5 
shows the method of doing this with an entry 
field where the font desired is 8-point Helv 
Italic with the foreground color red. 





Presentation parameters must be in the proper 
format to allow them to be properly set, as 
shown in Figure 6. Also, presentation 
parameters are inherited from the parent. In 
this case, the control should query the 
presentation parameters to see what they are 


ee ee 


by using the WinQueryPresParam function without 
the QPF_NOINHERIT flag. 


The next magical area to consider is the 
keyboard. How does the control know which 
control to move to when the user presses the 
tab key? Well, by handling the WM_CHAR message 
and looking for the VK_TAB key press, you only 
need to use the WinEnumDlgItem function to 
determine the next tab item. Likewise, when 
the user presses a cursor key, he or she uses 
the same function to determine the next or 
previous group item. 


SETTING UP THE CONTROL 


There are two ways to set up the control: 
during initialization and with messages. You 
will see throughout the OS/2 PM architecture 
that both methods are implemented. For 
example, you can use the ENTRYFDATA structure 
to set up an entry field for the maximum 
length of text the control can handle along 
with the starting and ending positions of 
selected text. This structure is only used during 
the entry field’s creation. If the structure is not 
present, the control is still created but uses 
certain defaults. The same task of setting the 
maximum input text and selection positions 
can be accomplished by sending messages to 
the control. For the setting of the text length, 
you would use the EM_SETTEXTLIMIT message, 
and, for the text selection, you would use the 
EM_SETSEL message. 


Good control design implies that the control 
should be able to handle a CTLDATA type 
structure, of which the ENTRYFDATA structure is a 
subset, whereas many of the static setup 
functions that a control needs to perform are 
defined within such a structure. For example, a 
control within OS/2 PM that does not follow 
this is the spin button, where you need to 
specify to the each of the servant controls who 
the master is through a message as shown in 
Figure 7. This could have been easily done 
through a CTLDATA type structure like the one 
shown in Figure 8, where, if the style of the 
spin button is a servant, the master owner of 
the control is specified in the structure and 
used when the control is created. Figure 9 
shows this method in a resource script file. 


The common element here is the ID of the 
master spin button. During the WM_Create 
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handling of the sping button, the window 
handle of the master could have been 
determined exactly in the same manner that 
Figure 7 does now with just a little further 
work. 





The basic goal is to minimize the amount of 
work you have to do to set up the control 
within your final application. This is 
particularly relevant when you use the control 
within dialogues, and the information is 
recorded within a dialogue template. 
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Figure 7: Example message 
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Figure 9. Possible spin button resource script file for CTLOATA implementation — 


EXAMPLE IMAGE BUTTON 
IMPLEMENTATION 


Figure 10 shows a custom control we will 
create as an example. This control is similar to 
the push button except that it allows fora 
bitmap image and text as integral components 
of the control. The image button control allows 
for two styles: IS_TEXTONBTN for Button 1 and 
IS_TEXTBELOWBTN for Button 2. 


Basically, we wanted the image button to 
allow the user to interact with it either through 
the keyboard or mouse. It had to allow for the 
images to be specified at the time of creation 
and at a later point through a message. As for 
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the images, three distinct images had to be 
allowed: button up, button down, and 
disabled. 


By understanding these basics, we can now 
begin the implementation of the image button. 





Since we can’t show all of the source code here, 


we will highlight 
the areas we think 
are important. We 
suggest that you 
try to gain access 
to the source 


code, which can Fis igure 10: eiemeple custom control 





Figure 11. Example dialogue containing custom controls 


/* --- CTLDATA Structure Definition ------------------------------- #/ 


Pretitttt titi titi ttt ttt trite ttt i ttt titi tit ti ttt ttt ttt tits esd 
/* NOTE: IDs for the bitmaps must be 0 < id < 65535 +/ 

/* This limitation is due to 05/2 PM Version 2.0 */ 
[HREKERARAAEALEREAASAAAEEE ASE EES ERE LEER EREEREREEEEELEREEREREREE REESE / 


typedef struct _IMAGEBUTTON /* ibtn 
{ /* Size: 16 Bytes 
LONG cb; /* Structure Size 
LONG idBitmap; /* Bitmap ID : Normal or Up Position 
LONG idBitmapDown; /* Bitmap ID : Down Position 
LONG idBitmapDisabled; /* Bitmap ID : Disabled 
} IMAGEBUTTON ; 


Figure 12: Image button CTLOATA definition 


be found on CompuServe in LIB13 of the 
OS2DF2 forum or through the other electronic 
means outlined at the end of the article, since it 
fully implements the control and also provides 
a little test applet to exercise the control. 
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A design goal for the button was that when the 
button was in the down position, a specific 
image could be shown if required. Also when 
the control was disabled, a third distinct image 
could be shown. Figure 11 shows the 
implemented controls within the test applet 
dialogue. 


In Figure 11, Button 1 is shown in its normal 
up position. The button is enabled and can be 
selected either with the mouse or the 
keyboard. Button 2 is shown in its disabled 
state, Button 3 shows emphasis, and Button 4 
shows the button when it is depressed. 


The CTLDATA structure defined for the image 
button is shown in Figure 12 and is very 
simple in design. The only rule, which is not 
sufficiently documented, regarding the CTLDATA 
structure is that the first field of the structure 
must be the size, which, in the case of the 
image button structure, is the cb field. OS/2 
PM uses this value to allocate memory for a 
copy of the data that is passed to the control in 
the WH_CREATE message. 


The field should not contain a value larger 
than 65,535, as the system will only allocate a 
64KB memory object. Since this limit may be 
lifted in future versions of OS/2, you may 
wish to set up the field as a ULONG, but limit the 
data structure size to be less than 64KB as we 
have done. This will allow us to expand the 
structure in the future to include new 
functionally. The corresponding resource 
script for the CTLDATA statement is also shown 
in Figure 13, and Figure 14 shows the 
equivalent source implementation. 


While we are all quite familiar with this 
outside view of the control, it is the inside part 
of the control that is the mysterious part and 
what we will now dive into. 


Part 1 of the control window procedure source 
code handles the WH_CREATE message, which is 
the first message it receives when it is created. 
Here is where we need to perform the control 
initialization and get the control ready for 
display. Since the source code is too long to 
show here, we will briefly describe what 
actions we perform in the creation sequence. 
First, we check to see that the CTLDATA structure 
that may be passed in mp1 is valid. This is 
done by checking the structure length element 
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cb to make sure that it is the correct value. If 
this value is correct or if the CTLDATA structure 
was not used, we allocate the internal control 
data memory that we need to be able to 
operate the control. 


The address of the structure is then placed 
within the reserved window words of the 
control. This will allow us to retrieve the data 
for the control as we require it when we 
process any messages of interest. 


When the IMAGEBUTTON CTLDATA information is 
present, we begin loading the bitmap images 
specified within structure, We make the 
assumption that the images are part of the 
executable resources and try to load the 
required bitmap image from those resources 
and create the bitmap handle for the image. 
Each bitmap image handle is saved within our 
internal control data so we can properly paint 
the required image on the button when 
required. 


If the bitmap images are not present or 
specified, we load the default images from the 
dynamic link library (DLL) that contains the 
implementation of the image button control, 
but you don’t have to implement a custom 
control in a DLL, you can implement it within 
an application. Most likely, you will want to 
make the custom control you create available 
to all the applications you create. 


After we process CTLDATA, we process the 
information contained within CREATESTRUCT that 
is passed to the control in mp2. This structure 
contains information as to the size and position 
of the control, the owner and parent of the 
control, the window style, text, and 
presentation parameters. You will need to 
process this information, especially the size 
and position, since you will not receive a 
WM_SIZE message as part of the window 
creation sequence. Also, save the owner and 
parent window information if you want to 
communicate back to either of these windows 
in the form of notification messages. In our 
case, we save this information within our 
internal control data. 


At this point, we also determine if presentation 
parameters are present by querying for those 
of interest, since we will use the colors defined 
later in painting the control. 





Finally, we perform the sizing operations on 
the control, calculate the various coordinates of 
the elements. These items are the polyline 
arrays, the text, and bitmap locations. 





Part 2 of the control source code handles 
control text and colors. Text setting and 
retrieval are handled through the 
WM_SETWINDOWPARAMS and WM_QUERYWINDOWPARAMS 
messages. The WM_SETWINDOWPARAMS message 


CONTROL "Button 1", IB_BUTTON1, 15, 25, 35, 27, "ImageBtn", 


IS_TEXTONBTN | WS_TABSTOP | WS_VISIBLE 


CTLDATA 16, 0, 100, 0, 101, 0, 102, 0 





Figure 13: Image button CTLDATA definition and resource implementation 


POINTL apt1[2] ; 
IMAGEBUTTON ibtn; 


/* Dialog Units Conversion Points */ 
/* Image Button CTLDATA +/ 


ibtn.cb = sizeof (IMAGEBUTTON) ; 
ibtn.idBitmap = 100L; 
ibtn.idBitmapDown = 101L; 
ibtn.idBitmapDisabled = 102L; 


apt1[0].x = 15L; 
apt1[0].y = 25L; 
aptl[i].x = 35L; 
apti[i].y = 27L; 


WinMapDlgPoints(hwndParent, aptl, 2L, TRUE); 


WinCreateWindow(hwndParent, "ImageBtn", "Button 1", 
IS_TEXTONBTN | WS_TABSTOP | WS_VISIBLE, 
aptl[0].x, apt1[0].y, aptl[1].x, aptl[i].y, hwndOwner, 
HWND_BOTTOM, IB_BUTTON1, (PVOID)&ibtn, (PVOID)NULL); 


Figure 14: Source code implementation 


takes any new text for the control and saves it 
within the internal control data; the next time 
the window is painted, the new text will be 
displayed. Conversely, WM_QUERYWINDOWPARAMS 
returns either the length of the current text for 
the control or the actual text, depending on the 
request. 


When the control is sized through the 
application explicitly, Part 3 of the code 
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custom DOS, Windows, and OS/2 applications? 


Introducing dbfLIB, the dBASE file access library for 
DOS, Windows, and OS/2 programmers. 






* A single set of functions for DOS, Windows, OS/2 1.3, OS/2 2.0 
* Royalty free Dynamic Link Libraries for: 
- Windows 3.0 and Windows 3.1 
- OS/2 1.3 (16-bit DLL) 
- OS/2 2.0 (32-bit DLL) 
* Static libraries for DOS and OS/2 applications. 
* Meaningful function names familiar to the XBASE programmer. 
* File and record locking. 
* Handle-based calls allows multiple instances of the same dbf file 
(very useful in multi-threaded OS/2 programs). 
* Create, update, and index dBASE files. 

















static libraries for DOS and OS/2. 
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S 220) East Tecumseh Rd. 
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(713) 537-0318 
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is the complete REXX package for OS/2 


If you're just getting into REXX, Personal REXX offers: 

« A full 32-bit implementation of REXX that is the fastest available 
* Complete documentation in the package 

* Free support by telephone, BBS, and CompuServe 

« Seven years of experience with REXX on a desktop platform 


But if you are already a REXX expert, there's much more: 

* True system-wide global variables 

* Interprocess Communication support for named pipes, semaphores, 
and the REXX external data queue 
Array operations like copying, sorting, and searching 
Advanced mathematical functions (trigonometric, logarithmic, 
exponential) 
Text-mode user interface support for windows, menus, and data 
entry screens. 
Date format conversion, regular expression file searching, and 
many other system services 
Full compatibility with IBM’s OS/2 and mainframe REXX 
implementations 


If you prefer, most functional enhancements are also available 
separately in "" REXXLIB add-on function package for 
OS/2 REXX. ) - 


Personal REXX is also available for DOS and Windows. 


P.O. Box 2157 
Saratoga, CA 95070 
Phone: 408-867-REXX 
Fax: 408-867-7489 
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handles the WM_SIZE message that is used to 
determine the new size of the control and 
recalculate the coordinates of the various 
drawing elements. 


Part 4 of the source code is used to handle the 
enabling and focus of the control. The WM_ENABLE 
message is processed to allow the control to 
know when it has been enabled or disabled 
and how it should paint itself due to this. By 
recording the state of the control, the paint 
process can select the appropriate bitmap to 
display. 


Likewise, the WH_SETFOCUS message is processed 
to allow the control to know when it has 
received or lost focus. This too allows the 
control to record the state so that when the 
paint process draws the text, emphasis can be 
removed or added to allow the user to know 
that the control has focus or not. 


User interaction with the control through the 
mouse and keyboard is contained in Part 5 of 
the source code. When the mouse button is 
pressed, we process the WM_BUTTONIDOWN 
message. In this processing, we denote in the 
internal control data that the button is now in 
the down state and that we are also in capture 
mode. Why Capture mode? Capture mode 
allows us to determine when Button 1 of the 
mouse has been released. But isn’t the 
WM_BUTTONIUP message sent to the control when 
the button is released? Well, yes and no. 
Confused? 


Mouse processing is really quite simple; it 
works just like a normal application window. 
Your window receives mouse messages sent to 
your window only when the mouse pointer is 
on top of it. But we want to know when the 
button is released, no matter where the pointer 
is. When the mouse is within the limits of the 
control, we will receive the button down and 
up messages. But if the user presses Button 1 
on the mouse within the limits of the control, 
keeps the button down and moves the mouse 
pointer outside the limits of the control, and 
releases it, the button-up message will be sent 
to the window in which the mouse pointer is 
now over, and the control will miss the button- 
up event. Therefore, by putting the mouse into 
mouse capture mode (WinSetCapture), when 
Button 1 of the mouse is pressed and only 
releasing the capture after Button 1 of the 
mouse has been released, we are assured of 


knowing the button-up event has occurred. 


When the button is released, we send a 
WM_COMMAND message to the owner window of 
the control to denote that the button has been 
selected. This is similar to the manner in which 
push buttons operate in OS/2 PM. 





For the keyboard, the WM_CHAR message is 
processed. Here, we check for the tab and 
cursor movement keys. Depending on the 
keystroke, we use WinEnumDlgItem for the next or 
previous control in which the focus should be 
placed on, since the user is indicating that he 
or she wishes to move to a particular control. 


MESSAGE PURPOSE 


IM_LOADBITMAPS 
IM_RESETBTN 
IM_SELECTBTN 
IM_SETBITMAP 


Loads requested bitmaps. 
Resets the button to the up position. 
Selects the button and sets it in the down position. 


Sets a specific bitmap image using a bitmap preloaded 
by the application. 

Simulates the click of the mouse pointer on the button, 
whether in the up or down position. Changes the state 
fromup to down or down to up. 


| IM_BTNCLK 





Table 2; Image button messages 


It is also in this part of the code that we 
process the mnemonic selections for the 
control. When the message is received, we 
check to see if the control contains a mnemonic 
by looking for a tilde (~) in the text of the 
control and if found, check the next character 
against the character provided by the message. 
When a match occurs, we return TRUE which 
causes the system to send the BY_CLICK message 
to the control. This occurs because we 
responded with DLGC_PUSHBUTTON to the 
WM_QUERYDLGCODE message. When we receive the 
BM_CLICK message, we process the message on 
the basis that the button has been pressed, 
sending the WM_COMMAND message to the owner 
of the control. 


The painting of the control is handled through 
the WH_PAINT message, which is Part 6 of the 
source code. This is an interesting message to 
handle since the OS/2 references publications 
do not document what a control should do. 
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The simple rule of thumb is that the 
background erasure is handled on your behalf 
by the owning window or dialogue, and the 
drawing into the control area uses the 
presentation space of the owning window. 
Hence, any attributes present in the owning 
window will be inherited. Also, you don’t 
need to worry about fonts and font sizes, since 
these can be taken care of through the 
PP_FONTNAMESIZE presentation parameter. The 
logical font and size will be automatically set 
for the presentation space, including scalable 
fonts. 


For the most part, the painting process is just 
the process of drawing the control. In the case 
of the image button, it is drawing the bitmap 
image that is to appear on the button. This 
image is determined in the drawing routine, 
since the state may have changed since the last 
drawing. In this case, it may mean selecting the 
bitmap for the up position, down position, or 
disabled state. 


Once the bitmap image is drawn using the 
information that was processed during the 
sizing operations, the beveled edges of the 
control are drawn. Using the coordinates 
Carmuiaica auring the sizing operations, a very 
ast Qrawing Mecnanism 1s Impiemented here. 


First, we set the drawing color and line types 
using GpiSetColor and GpiSetLineType. Next, we 
set the initial starting coordinate (in this case in 
the lower left corner of the bottom window) 
with GpiMove. Then we draw as many lines as 
necessary with GpiPolyLine. We draw the 
beveled edges of the control until they are 
complete and then draw the button border 
using a similar method. 


Last, we draw the text of the control and, if 
emphasis is required, we draw the emphasis 
dots around the text using the GpiSetLineType, 
GpiMove, and GpiPolyLine functions. You can, 
during the paint processing, check to see if the 
style of the control has changed, in which case 
you may want to recalculate the various 
component coordinates before painting and 
save the new style internally. In essence, what 
you are trying to do here is use a cache of 
information to allow the painting to be as fast 
as possible without having to recalculate the 
components of the control each time. 


Part 7 of the source code contains the message 
handling for the control specific messages sent 
from the application to the control. These 
messages, shown in Table 2, are designed to 
allow the application that owns the control a 
means of setting the appearance of the image 
button. The IM_LOADBITMAPS message, which is 
used to load bitmaps from the executable file, 
uses the same method within the WM_CREATE 
message. It allows you to dynamically change 
the images for an image button without having 
to destroy and recreate it. The messages you 
send the control can be anything you require 
and should be extendable. 


The last part of the source code, Part 8, 
contains the WH_DESTROY message. When we 
receive this message, we know that the control 
is being destroyed, and we should delete the 
loaded bitmaps and release the memory 
allocated, 


CONCLUSION 


Knowing that controls are in fact just 
windows and that certain operations are 
performed on their behalf, it is easy to 
implement custom controls for applications. 
For example, you can easily create a pattern 
custom control that is based on the 
GpiSetPattern function or a simple line control 
based on the GpiLine function. Creating 
controls is not all that difficult if you follow a 
few simple rules. Using the example control 
that is the basis of this article, you can create 
your own control in a very short period of 
time. In our next article, we explain in more 
detail those mysterious presentation 
parameters and the design of a custom 
control. 
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The complete source code for the sample program in this article can be downloaded from the 


| following electronic sources: 


¢ In Europe, the source code is available on the International OS/2 Users Group bulletin board 





service at (44) 0454 633 197 or (44) 0454 633 420. 


® In the U:S., call the IBM National Support Center bulletin board service at (404) 835-6600. The 
source code is in file area 11, named OS2DCTRL.ZIP. 
| 


* In Canada, call the IBM bulletin board service at (416) 946-4255 (Toronto), (514) 938-3022 
(Montreal), or (604) 664-6466 (Vancouver). The source code is in file area 30 in the file 


OS2DCTRL.ZIP. 


° On CompuServe, the source code is in LIB13 of the OS2DF2 forum. 


* On VM (IBM node) source code can be accessed by issuing the following command: 
REQUEST CUSTCTRL FROM BANZAI AT CARVM3. 
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Developing Applications 
With Query Manager 


by Alan S. Eisen 


The OS/2 Query Manager component of Extended 
Services far OS/2 has many facilities for creating 
sophisticated database applications. Through the 
use of panels, menus, and procedures, many 
applications can be developed without additional 
fools. This article is intended to provide the 
beginning developer with some tips for using these 
facilities and linking them together to create 
complete applications. These tips were gathered 
over tite last ttvo years as [ developed an application 
to manage tivo infernal IBM programs, Systenis 
Assurance and Critical Situations (Critsit). 


USING PANELS 
Panel Design 


Pe are used to ease data access. They 
allow developers to label and position fields 
on the screen to make them meaningful to users. 


The amount of data on any one screen should 
be limited to increase readability, but panels 
can be continued well beyond a single screen. 
Maximizing the Query Manager session when 
designing panels and working with a full 
screen rather than an arbitrarily sized window 
gives the user a reference point from which to 
see the entire panel. The user can run the 
application in a window, but if it is designed 
for a standard-size screen the user will know 
the maximum boundary. 


When establishing an initial screen design, the 
easiest method is to select Specify/Default 
Definition, which tells the Query Manager to 
build the default panel with each field listed 
along the left side of the screen. This eliminates 
the need to mark each field and its text, as they 
are already on the screen and can be 


individually manipulated. This is most 
convenient when large numbers of fields are 
involved, as each field and text item must be 
marked individually. The disadvantage is 
apparent when fields must be moved from one 
screen to another. Once the default is 
established you can continue the panel design, 
specifying subtables and lookup tables and 
renaming the fields. 


As you position fields on the screen, it is 
helpful to align information vertically and 
horizontally to make it more readable. For 
example, a user can add information fora 
systems assurance review, as shown in Figure 
1. Information about each review type is 
aligned horizontally. The dates, risk 
assessments, and waivers for all reviews are 
aligned vertically. This matrix of information 
makes completion easier for the user and 
allows fields to be described in groups rather 
than individually. 


Linking Panels 


The Critsit application, shown in Figure 1, 
requires a lookup table that contains IBM 
product information. It is more efficient to 
store descriptions of each product once than to 
repeat the descriptions for each row in the 
primary table. On occasion, the Critsit table 
will need to reference a product that has not 
yet been entered into the product table. Toa 
new developer, it may appear that there is no 
mechanism for linking one panel to another. 
For example, when you press PF4 in the 
Panel /Operation Command column, there is 
no option to run another panel. 


The way to do this is to use the RUN PANEL or RUN 
PROC command from the Panel/Operation 
Command column, which allows you to 
dynamically link from one panel to another. It is 
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then possible to jump out of the Critsit panel into 
the product panel, enter the new product, and 
return just where you left off without losing data. 


Function Key Standards 


As you create panel operations, it helps to 
standardize function keys for the advanced 
user. A convenient group of function keys to 
use is Shift + PF4/5/6/7, which are unused 
keys for panels that can be assigned to your 
application. Consistency is important with 
these keys. For example, PF4 should always 
take you to the product table, whether it is 
accessed from the Critsit panel or the Systems 
Assurance panel. The Query Manager 
provides a good example of moving between 
forms, reports, and queries. 


Initializing Panel Value Fields 


After the individual panels are designed, it 
may be helpful to initialize the values of select 
fields (for example, by setting a timestamp 
field with the current timestamp). Creating a 
procedure to be run as the panel’s Instance Rule 
(Add) allows you to initialize panel field values. 
Figure 2 shows a simple example that 
establishes a variable, temp, with the current 
timestamp. The DATETIME panel field is set equal 
to temp. Because the instance rule is run before 
each new panel is displayed, the value is 
always updated. If the field is not going to be 
altered by the user, it doesn’t need to appear 
on the panel, although it must be defined in 
the table fields option. 


If your timestamp column requires a unique 
value and there are simultaneous system users, 
this method will not guarantee that another 
user will not have the same value. If two users 
have the same value, the Database Manager 
will not allow the second row insert and the 
user will have to exit the panel and begin again. 


As you become comfortable with linking 
panels and creating system variables, it will 
become obvious that some information from 
the first panel belongs in succeeding panels. 
You can capture this information for the user, 
avoiding data reentry. A simple example of 
this situation shows up whenever you attempt 
to add new products associated with a specific 
critical situation. The user may choose to add a 
new product to an existing Critsit; the 
PULL_VAR_CRIT procedure is executed instead of 





the RUN PANEL action in the panel operation 
command. It captures the value of the current 
KEY value (the Critsit number), stores it ina 
global variable, and runs the panel to add the 
new product. The second panel, CRITSIT_PROD, 
has an instance rule (Add) that runs the PUSH_VAR 
procedure, which fills the KEY value with the 
value taken from the Critsit panel. This simple 
technique, which combines panels and 
procedures, allows the user to move easily 
between functions without losing or reentering 
data. The PULL_VAR_CRIT and PUSH_VAR procedures 
are shown in Figure 3. 





[9 Query Manager for FSMCA 
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Figure 2: Initializing a field 


USING MENUS 


Menus are created much like panels, except 
you define menu actions rather than fields. 
Menu actions can be linked directly to panels, 
queries, procedures, or other menus. You may 
also run other valid Query Manager 


commands as listed in the Help panel. Like 133 
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panels, menus should be carefully designed so 
their functions are obvious. Figure 4, an 
example of what not to do, shows a menu that 
tried to squeeze too much into one screen. 





Procedure: PULL_VAR_CRIT 

/*This procedure takes the KEY value from the starting panel and 
**stores it into a global variable and then calls the next panel 
**for data entry*/ 

‘GET CURRENT (vari = KEY)’ 

‘SET GLOBAL (glvar = vari)’ 

‘RUN PANEL CRITSIT_PROD (MODE=ADD) ’ 


Procedure: PUSH_VAR 

/*This procedure takes the global variable “glvar” and moves the 
/+value into the current variable KEY. It is used in the Panel 
/*Instance (Add) to pre-fill the field.*/ 

‘GET GLOBAL (temp=glvar) ’ 

‘SET CURRENT (KEY=temp) ‘ 


Figure 3: Moving a value between panels 
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_ Product Information Maintenance 


Figure 4: Menus—ivfiat not to do 


A better design for the menu in Figure 4 would 
be to take the three major components, Systems 
Assurance, Critsit, and Area Quality Council, 
and make each one a menu selection. The menu 
action for these three items links to three 
separate menus with more room for options. 
Each menu item must also have a unique single- 
character mnemonic. Unfortunately, the short 
names that were used did not provide enough 
unique values so random letters such as Y and Z 
were used. This does not make for either an 








attractive screen or mnemonics that are 
meaningful to the user. 


A final benefit of nesting menus is the ability 
to control user access. In Figure 4, all functions 
of the database are displayed. A user who only 
needs access to Critsit still views and can still 
choose the other selections. Although 
database manager security (GRANT/REVOKE) 
prevents access, users tempted by the function 
will receive only a marginally helpful error 
message from the system. A nested menu 
allows users with access to the whole system 
to see all selections, while those with limited 
access can be started at the submenu. 


LINKING WITH PROCEDURES 


Query Manager procedures are not a 
substitute for a high-level language, as you 
cannot directly incorporate SQL statements 
within the procedure. They do, however, 
provide program control between other Query 
Manager functions such as queries and forms. 


As noted in the documentation, a procedure 
must begin with a comment, delineated with 
the characters /+ and */, as ina REXX or PL/I 
program. Proper documentation within the 
program makes it easier for someone else to 
understand what you have done or for you to 
understand it when you come back in six 
months. These comments are not the same as 
comments in an SOL query, which precede the 
comment with two dashes. 


One use of procedures is demonstrated by the 
Systems Assurance application, which creates 
separate reports for multiple IBM marketing 
branches. Because the reports need to be 
distributed electronically, a separate file for each 
branch is needed. A query that sorts by branch is 
not the answer, as it creates only one file. 


Figure 5 shows a simple procedure that sets 
the value of a variable, BRANCH, for each run of a 
single query. The form used to print the 
output uses the same variable to print the 
branch name on the report. The PRINT REPORT 
lines are shown as continuation lines for 
printing purposes only. Continuation lines are 
not supported. 


The procedure and query editors support OS/2 
Cut and Paste facilities. To copy lines in the 
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procedure, highlight the selected text and press 
Ctrl+Insert. To paste the text, use Shift+Insert. 


Multiple Queries vs. Row Logic 


While using a REXX program to perform 
individual row manipulation is effective, it 
may be more complicated than necessary. 
Procedures and queries do not support host 
variables, which may make row manipulation 
difficult. However, if you look at your 
program differently and create a query that 
selects a unique set of rows, procedures and 
queries may be used exclusively. 


Perhaps you want to import new data into a 
temporary table before either inserting it into 
an existing table or update existing rows. The 
REXX methodology would read each row 
from the temporary table, see if a 
corresponding row exists in the target table, 
and then perform an insert or update. A 
simpler method that can be written solely in 
Query Manager is to write a query that does 
an update where the two tables intersect and 
another query that inserts rows when they 
don’t. A procedure can be written that first 
runs the import and then the queries and that 
can be run as needed. 


This allows for the definition of a few queries 
that select just the data that satisfies each 
required case and manipulates all the rows. 
Rethinking processes to satisfy single or 
multiple queries allows the Database Manager 
to perform more of the work, which makes the 
application more efficient and easier to develop. 


CREATING SEQUENTIAL 
NUMBERS 


When there is no obvious way to create a 
unique row value, the easiest way is to create a 
sequential number. While the Query Manager 
will not create sequential numbers 
automatically, it is easy to do. The following 
method is not sufficient for an application with 
many simultaneous users, however; it will 
likely cause duplicate values. 


Figure 6 shows the procedures and queries 
used in addition to two panels. The first panel 
is the user data entry panel, and the second is 
an unseen interim panel called MAX_VALUE. 


The application shown in Figure 6 was created 
to store customer feedback information. The 
first procedure, MASTER_PROC, begins the 
sequential numbering process. The first 
iteration of this process can be somewhat time 
consuming, as the system must load 
information into memory. It also requires a 
dummy row with a value of at least zero to be 
entered into the table. Once the table is 
populated, the dummy row can be deleted. 








F igure 5: Linking queries 


MASTER_PROC runs a query that selects the next 
sequential number. The value is saved in a 
temporary table and then the MAX_VALUE panel 
is run. The MAX_VALUE panel gets the value from 
the temporary table and places it into a global 
variable. There are two rules for this panel: the 
Panel Search Query rule runs the GET_VALUE 
query and the Procedure (Change) rule runs 
the GET_VALUE procedure. 


Finally, the master procedure runs the actual 
data entry panel, known as FEEDBACK_CARD. This 
panel has a Procedure (Add) instance rule of 
PUT_VALUE, and the Add and Next action has 
been changed to run the procedure ADD_PANEL. 
ADD_PANEL is similar to the master procedure in 
that it processes a selection of the next 
sequential number so many rows can be 
entered without leaving the data entry panel. 


Queries, panels, and procedures provide 
tremendous flexibility in application 
developement. The Database Manager upon 
which they are built is very robust, providing 
needed security and integrity. These applications 
can be used either in a stand-alone mode or by 
many users on a local area network. 
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Procedure: MASTER_PROC 
/*Master procedure for creating a sequential number in the problem_number field+/ 
‘RUN QUERY max_value (INTERACT=no)’ /#Selects next number */ 

‘SAVE DATA AS max_value_table (COMMENT="Temporary Table”, CONFIRM=no,REPLACE=yes) 


/*The next panel gets the value from the temporary table and puts it into a global variable*/ 


‘RUN PANEL max_value (mode=change) ’ 


‘RUN PANEL FEEDBACK_CARD (mode=add)’ /*Runs actual data entry panel*/ 


Procedure: GET_VALUE 


/*The MAXVALUE panel displays the single next sequential problem number and sets a global 
/*variable that will be picked up by the proc run by the actual FEEDBACK panel.*/ 


/*maxvalue is the name define in Table Fields*/ 


‘GET CURRENT (vari=maxvalue) ’ 
‘SET GLOBAL (var2=var1) ’ 
‘QUIT PANEL’ 


Procedure: PUT_VALUE 


/*These functions take the global variable set from the max_value panel and makes it a 
/*current variable when this value is called from the actual data entry panel.+/ 


‘GET GLOBAL (var3=var2) ’ 
‘SET CURRENT (KEY=var3) ’ 


Procedure: ADD_PANEL 


/*This procedure completes the first add of an item and then re-executes the function 
/*to select the next sequential number and re-display the add panel*/ 


‘ADD’ 
‘RUN QUERY max_value (INTERACT=no) ‘ 


‘SAVE DATA AS max_value_table (COMMENT=”"Temporary Table”, CONFIRM=no, REPLACE=yes) ’ 


‘RUN PANEL max_value (mode=change) ’ 


Query: MAX_VALUE 


SELECT MAX(problem_number)+1 FROM feedback_table 


Query: GET_VALUE 
SELECT * FROM max_value_table 


Figure 6: Sequential number routines 
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Capture images from anywhere on the screen directly into the 

image editor. Create bitmaps, icons and cursors from the captured image. 
Customize the look and feel of your applications— 


directly extract, modify or replace any resource in any program file, 


EXE, DLL—no source code is needed. 
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Translate 
all your 
foreign languages without Se resources 








Translate applications into 
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having access to the applications source code— 







WINDOWS. 


oe I 


directly modify all messages, menus and dialogs into any national language. 


Edit, copy and paste resources directly into and from any EXE, RES, 





DLL, RC program file. Eliminate the time consuming edit-compile-link MICROSOFT. 
WINDOWS NT. 


7 he Stirling Group 
172 OLD MILL DRIVE sralistotainio: iL 60193 e USA 1 -800-3 SH \ ELI 


NT applications utilizing the transparent and automatic resource 1-800-374-4353 
CALL 708-307-9197 * FAX 708-307-9340 


CompuServe: GO STIRLING ¢ MCI Mail: STIRLING 


cycle—increasing your productivity dramatically, 


Migrate your applications to new 32-bit 0S/2 2.0 and 


translation capabilities. Create your resources once on 


any platform and instantly use them on any other platform. 






Windows and 0S/2 
have in common? 
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ObjectVision for Windows 


A:Your ObjectVision applications. 


Borland’s ObjectVision® brings Microsoft® 

Windows and OS/2° users together. Only 

ObjectVi ision allows you to write an appli- 

| cation once for use under both Windows 
and OS/2. And access the same data, 

| _ regardless of platform. That’s because 
Objec tVision, the world’s easiest tool for 

| creating Windows applications, is now also 

available for OS/2. 


| Visual programming 

| makes it easy 

ee revolutionary visual 
programming tech- 
niques, ObjectVision 
makes it easy for the 
people who know 
the business issues to 
develop and maintain 
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ObjectVision for OS/2 





Creating Windows or OS/2 applications is FREE runtime version 
as easy as A-B-C. Simply: Because a runtime version is included 
A. Draw your application interface using free, it's easy to distribute your customized 
the convenient form tool. applications throughout your company. 
B. Apply your business rules visually. With ObjectVision, fully interoperable 
C. Connect your application to your Windows and OS/2 applications are 
existing : database. Or create your here today! 
own database. — a = <= <= =< aon 
In Windows and OS$/2, ObjectVision makes See your dealer today to get your own t 


it easy to create, modify, and run your own fl copy of ObjectVision for Windows or 0S/2, f 
OR call 1-800-331-0877, ext. 6622 to 
request your ObjectVision for Wiridows [ 


FREE TRIAL DISK 


In Canada, call 1-800-461-3327 


OBJECTVISION 


interactive applications. And the OS/2 ver- 
sion giv es you easy access to REXX as well 


as DLLs. 


Easy accesstodata 
ObjectVision is the ideal front end to your i 


data because it integrates information from 
different databases under one familiar. 
graphical user interface. Your ObjectVision 
applications can easily connect to informa- 
tion stored in Paradox” dBASE® Btrieve, 
Database Manager, and ASCII formats. 


OBJECTVISION 


BORLAND 


BORLAND 


The Leader in Object-Oriented Programming 
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